architect

Every decision in PLAN.md must be justified. No "we'll figure it out during implementation."

Key SDD concepts used here:

• Touchpoints: Every file path that will be created or modified
• Effects: Every deterministic side-effect the system produces
• Mixins: Reusable behavioral patterns (e.g., requires_auth)
• Arch Tags: Inline markers that agents can read to retrieve constraints

IF user has specified tech stack: VALIDATE: Does the stack support all requirements in SPEC.md? IF gaps exist: FLAG: "{requirement} may not be well-served by {tool}. Consider {alternative}?" AWAIT user decision

IF user has NOT specified tech stack: ANALYZE requirements to determine needs: - Frontend rendering strategy (SSR, SPA, static, hybrid) - Backend requirements (API complexity, real-time needs, background jobs) - Data storage needs (relational, document, key-value, graph) - Authentication complexity - Deployment target

PROPOSE stack as a table: | Layer | Choice | Rationale | |-------|--------|-----------| | ... | ... | ... |

INCLUDE: Why alternatives were NOT chosen (brief)

AWAIT: User approval or modification

</step>

<step id="2" name="System Architecture">
Define the system's structural blueprint:

- **System boundaries**: What code you own vs. external services
- **Component map**: Major modules/services and their single responsibilities
- **Data flow**: How data moves through the system (request → response)
- **Integration points**: External APIs, third-party services, databases
- **Architecture pattern**: Monolith / microservices / serverless / hybrid + rationale

Generate architecture diagram:
```mermaid
graph TD
    A[Client] --> B[API Layer]
    B --> C[Business Logic]
    C --> D[Data Layer]
    D --> E[(Database)]
    B --> F[Auth Service]

Adapt the diagram to match actual system complexity. Don't over-diagram simple systems.

Schema definition:

Field	Type	Constraints	Description
id	uuid	PK, auto-generated	Unique identifier
created_at	timestamp	NOT NULL, default NOW	Creation timestamp
...	...	...	...

Relationships:

erDiagram
    USER ||--o{ POST : creates
    POST ||--o{ COMMENT : has

Indexes: List indexes needed for query performance.

Migration strategy: How the schema will be created and evolved.

• Initial migration creates all tables
• Future changes via numbered migrations
• Rollback strategy for each migration

### {METHOD} {path}
**Purpose**: {what this endpoint does}
**Auth**: {required level — public, authenticated, admin}

**Request**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| ... | ... | ... | ... |

**Response (success)**:
```json
{
  "field": "type — description"
}

Error Responses:

Status	Code	Description
400	VALIDATION_ERROR	{when this occurs}
401	UNAUTHORIZED	{when this occurs}
404	NOT_FOUND	{when this occurs}

Group endpoints by domain (e.g., Auth, Users, Content).
</step>

<step id="5" name="File Structure">
Define the COMPLETE project file structure with purpose annotations:

project-root/ ├── src/ │ ├── app/ # Next.js app router (or equivalent) │ │ ├── layout.tsx # Root layout with providers │ │ ├── page.tsx # Landing page │ │ └── (auth)/ # Auth route group │ │ ├── login/page.tsx # Login page │ │ └── signup/page.tsx # Signup page │ ├── components/ # Shared UI components │ │ ├── ui/ # Base design system components │ │ └── features/ # Feature-specific components │ ├── lib/ # Shared utilities and configs │ │ ├── db.ts # Database client │ │ ├── auth.ts # Auth utilities │ │ └── utils.ts # General utilities │ └── api/ # API routes / server functions ├── specs/ # SDD specification documents │ ├── SPEC.md # Product specification │ ├── PLAN.md # Technical plan (this document) │ └── TASKS.md # Implementation tasks ├── CLAUDE.md # Agent context file ├── llms.txt # Spec document index for LLMs ├── package.json └── ...config files