# Architecture — {{Product Name}}

> _This is what every executor agent reads before writing code. It defines the tech stack, patterns, conventions, and structural decisions for the project. Updated as decisions are made via `/forge:decide` or during builds._
>
> _Last updated: {{date}}_

---

## Product Overview

{{Brief product description — reference DOMAIN.md for the full domain model. 1-2 sentences here, just enough for an executor to understand what they're building.}}

---

## Tech Stack

### Core

| Layer               | Technology                    | Notes                                |
| ------------------- | ----------------------------- | ------------------------------------ |
| **Language**        | {{e.g., TypeScript}}          | {{version or relevant details}}      |
| **Framework**       | {{e.g., Next.js 15}}          | {{App Router / Pages Router / etc.}} |
| **Database**        | {{e.g., Convex / PostgreSQL}} | {{hosted where?}}                    |
| **Auth**            | {{e.g., Clerk / NextAuth}}    |                                      |
| **Deployment**      | {{e.g., Vercel / AWS}}        |                                      |
| **Package Manager** | {{e.g., pnpm}}                |                                      |

### Key Libraries

<!--
Only list libraries that are architectural decisions — things an executor
needs to know about to maintain consistency. Not every npm dependency.
-->

| Purpose                    | Library                   | ADR                |
| -------------------------- | ------------------------- | ------------------ |
| {{e.g., Forms}}            | {{e.g., React Hook Form}} | {{ADR-NNN or "—"}} |
| {{e.g., Validation}}       | {{e.g., Zod}}             | {{ADR-NNN or "—"}} |
| {{e.g., UI Components}}    | {{e.g., shadcn/ui}}       | {{ADR-NNN or "—"}} |
| {{e.g., State Management}} | {{e.g., Zustand}}         | {{ADR-NNN or "—"}} |

---

## Project Structure

### {{Monorepo / Single Package}}

<!--
If monorepo, show the package graph. If single package, show the directory layout.
This is what the package-analyst agent reads to understand boundaries.
-->

```
{{project-root}}/
├── {{directory}}/ — {{purpose}}
├── {{directory}}/ — {{purpose}}
├── {{directory}}/ — {{purpose}}
└── {{directory}}/ — {{purpose}}
```

### Package Boundaries (Monorepo Only)

<!--
If this is a monorepo (Turborepo, Nx, etc.), document the package graph:

| Package | Purpose | Depends On | Consumed By |
|---------|---------|-----------|-------------|
| packages/domain | Shared types and business logic | — | apps/web, apps/api |
| apps/web | Frontend application | packages/domain, packages/ui | — |
| apps/api | Backend API | packages/domain | apps/web |

This is critical for the package-analyst agent to track cross-package impact.
-->

---

## Architectural Patterns

### API Design

<!--
Document the API pattern in use. Executors must follow this consistently.

Example:
- **Pattern**: Convex functions (queries, mutations, actions)
- **Naming**: `featureName.operationName` (e.g., `tours.create`, `vehicles.list`)
- **Validation**: Zod schemas on all inputs, defined in the function file
- **Error handling**: Throw ConvexError with structured error codes
- **See**: ADR-003 for why Convex over REST
-->

{{Describe the API pattern or note "To be decided during first build"}}

### Data Modeling

<!--
How domain entities map to the database. Not the full schema — the patterns.

Example:
- Convex tables map 1:1 to domain entities from DOMAIN.md
- Use references (Id<"tableName">) for relationships, not embedding
- Soft delete via `deletedAt` timestamp, never hard delete
- All timestamps in UTC
-->

{{Describe data modeling patterns or note "To be decided during first build"}}

### Frontend Patterns

<!--
Component structure, state management, routing conventions.

Example:
- Feature-based directory structure: `features/tours/`, `features/vehicles/`
- Each feature has: components/, hooks/, types.ts
- Shared UI in `components/ui/` (shadcn/ui based)
- Form pattern: React Hook Form + Zod schema + server action
- See: ADR-005 for component architecture decision
-->

{{Describe frontend patterns or note "To be decided during first build"}}

### Error Handling

<!--
How errors are handled across the stack.

Example:
- Backend: Typed error codes, never raw strings
- Frontend: Error boundaries per feature, toast for user-facing errors
- Validation: Fail at the boundary (API input), trust internally
-->

{{Describe or note "To be decided"}}

### Testing Strategy

<!--
What gets tested and how. Reference the test-strategist agent's approach.

Example:
- Unit tests: Business logic in domain layer (Vitest)
- Integration tests: Convex functions with test database
- E2E tests: Critical user flows (Playwright)
- Coverage target: Business logic 90%, UI 60%, E2E for happy paths
-->

{{Describe or note "To be decided during first build"}}

---

## Conventions

### Naming

<!--
Consistent naming across the codebase. Executors follow these strictly.

Example:
- Files: kebab-case (tour-planning.tsx)
- Components: PascalCase (TourPlanning)
- Functions: camelCase (createTour)
- Database tables: snake_case (tour_stops)
- Domain terms: Use Ubiquitous Language from DOMAIN.md (Fahrzeug, not Vehicle)
-->

| What         | Convention                        | Example     |
| ------------ | --------------------------------- | ----------- |
| Files        | {{convention}}                    | {{example}} |
| Components   | {{convention}}                    | {{example}} |
| Functions    | {{convention}}                    | {{example}} |
| Database     | {{convention}}                    | {{example}} |
| Domain terms | Use DOMAIN.md Ubiquitous Language | {{example}} |

### Git

<!--
Commit and branching conventions. Referenced from forge.yaml config.
-->

- **Commit style**: {{conventional / gitmoji / simple}} (from forge.yaml)
- **Branching**: {{none / feature / milestone}} (from forge.yaml)
- **Atomic commits**: One commit per logical change (enforced by executor agent)

### Code Style

<!--
Formatting and linting. Keep brief — the tooling enforces most of this.
-->

- **Formatter**: {{Prettier / Biome / etc.}}
- **Linter**: {{ESLint / Biome / etc.}}
- **Config location**: {{path to config files}}

---

## Infrastructure & Deployment

<!--
How the application gets deployed and run.

Example:
- Hosting: Vercel (frontend), Convex (backend)
- Environments: dev (local), staging (preview deploys), production
- CI/CD: GitHub Actions → Vercel auto-deploy
- Environment variables: Documented in .env.example
-->

{{Describe or note "To be decided"}}

---

## Security Considerations

<!--
Authentication, authorization, data protection patterns.

Example:
- Auth: Clerk with organization support
- Authorization: Row-level security in Convex via helper functions
- Data: Tenant isolation via organizationId on all records
- Secrets: Environment variables, never committed
-->

{{Describe or note "To be decided"}}

---

## Revision History

| Date     | Change                          | ADR           |
| -------- | ------------------------------- | ------------- |
| {{date}} | Initial architecture documented | `/forge:init` |

<!--
Track architectural changes with links to the ADR that drove them.
This creates an audit trail of how the architecture evolved.
-->
