Vertical Slice Architecture

---
name: vertical-slice-architecture
version: 1.0.3
description: Enforce Vertical Slice Architecture (VSA) when building applications in any language (Go, .NET/C#, Java, Kotlin, TypeScript, Python, etc.) and any type (web API, mobile backend, CLI, event-driven). Organize code by feature/use-case instead of technical layers. Each feature is a self-contained vertical slice with a single entry point that receives the router/framework handle and its dependencies. Use when the user says "vertical slice architecture", "VSA", "organize by feature", "feature-based architecture", "slice architecture", or when building a new app or feature and the project already follows VSA conventions. Also use when reviewing or refactoring code to align with VSA principles.
---

# Vertical Slice Architecture

## Quick Reference: The 5 Rules

1. **One feature = one directory** containing handler, request/response types, validation, and tests
2. **One entry point per feature** — a setup/registration function that receives the router and dependencies. Name varies by convention (`Setup`, `RegisterRoute`, `Map`); the role is the invariant, not the name.
3. **Minimize coupling between slices, maximize coupling within a slice**
4. **No premature abstractions** — no shared repository/service layers until genuine duplication emerges across multiple slices
5. **Test each feature primarily through its entry point**, verifying outcomes (DB state, API calls, response). Platform/adapter tests are also encouraged.

## Project Structure

```
{project}/
  features/              # or internal/features/ (Go), Features/ (.NET)
    {domain}/            # orders/, users/, kvs/
      {operation}/       # create/, list/, delete/
        handler          # Single entry point + orchestration
        request/response # DTOs
        validator        # Input validation (optional)
        test             # Co-located integration test
        internal/        # Feature-private helpers (optional)
  platform/              # or Infrastructure/ — shared cross-cutting concerns
    middleware/           # Auth, error handling, idempotency
    database/            # Connection pooling, circuit breakers
    observability/       # Metrics, tracing, structured logging
    opqueue/             # Operation queues, outbox patterns (if needed)
  main                   # Composition root wires features + infrastructure
```

## Workflow: Adding a New Feature

1. Create directory: `features/{domain}/{operation}/`
2. Define the handler with a single exported setup function
3. Define request/response types (inline for simple cases)
4. Add validation logic
5. Register in the composition root (`main`)
6. Write integration test that calls the setup function, sends request, verifies outcomes

## Workflow: Adding Cross-Cutting Concerns

Place in `platform/` (not inside a feature). Examples:
- Auth middleware, error handling, request logging
- Database connection pooling, circuit breakers
- Idempotency middleware, operation queues, event notifications
- Observability (metrics, tracing, structured logging)

## Workflow: Extracting Shared Logic

Only extract when genuine duplication emerges across multiple slices (use judgment — the "3+ slices" heuristic is guidance, not a hard rule):
- Duplicate business rule: extract to a domain entity/value object
- Duplicate data access pattern: extract to a shared repository (only for that specific pattern)
- Duplicate HTTP helper: extract to `platform/httpx/`

## Key Decisions by Language

Detect the project's language/framework and consult the appropriate reference:
- **Patterns per language**: See [references/patterns-by-language.md](references/patterns-by-language.md) for Go, .NET, Java, TypeScript, Python
- **Testing per language**: See [references/testing.md](references/testing.md) for testcontainers, mock verification, integration test patterns
- **Core principles**: See [references/principles.md](references/principles.md) for detailed rules, anti-patterns, and shared domain model guidance

## Single Entry Point Contract

Every feature exposes one primary setup/registration function. Internal types stay private. The entry point name is conventional — the invariant is: **one public function per feature that wires the slice to the framework**.

- **Go** — convention `Setup` or `RegisterRoute`; signature `func Setup(r gin.IRoutes, repo Repository)`; DI via explicit params.
- **.NET** — convention `Map` (static); signature `static void Map(IEndpointRouteBuilder app)`; DI container resolves deps in handler.
- **Java/Kotlin** — `@RestController` class discovered by component scan; Spring DI (constructor injection).
- **TypeScript** — convention `setup`; signature `function setup(router: Router, db: Database): void`; DI via explicit params.
- **Python** — convention `setup`; signature `def setup(router: APIRouter, db: Database) -> None`; DI via explicit params or `Depends()`.

**Exceptions**: Versioned APIs may have `SetupV1`/`SetupV2` wrappers sharing internal handler wiring. Frameworks with auto-discovery (Spring, NestJS) use the controller/module class itself as the entry point.

## Testing

See [references/testing.md](references/testing.md) for full testing strategy per language, including feature integration tests, platform/adapter tests, mock verification patterns, and test naming conventions.