# <!-- Powered by BMAD™ Core -->

# Create Architecture Document Task

## Purpose
Document the technical architecture of a JavaScript/TypeScript full-stack application to guide implementation and ensure team alignment.

## When to Use
- Starting a new greenfield project
- Major system refactoring
- Adding significant new capabilities
- Onboarding new team members
- Technical planning phase

## Prerequisites
- Requirements analysis complete
- Technology stack decision made (or to be documented)
- Understanding of scale and performance needs
- Budget and timeline constraints known

## Architecture Document Structure

### 1. Executive Summary
- **System Overview** (2-3 paragraphs)
- **Technology Stack** (Frontend, Backend, Database, Infrastructure)
- **Architecture Pattern** (Monolith, Microservices, JAMstack, Serverless)
- **Key Decisions** (3-5 major decisions with rationale)
- **Scalability Overview**

### 2. Frontend Architecture
- **Framework:** React/Next.js version with justification
- **Build Tool:** Vite, Webpack, Next.js built-in
- **State Management:** React Query + Zustand/Redux/Context
- **Routing:** File-based (Next.js) or React Router
- **Styling:** Tailwind, CSS Modules, Styled Components
- **Component Structure:** Folder organization
- **Code Splitting:** Strategy for optimization
- **SEO Strategy:** SSR, SSG, or CSR approach

### 3. Backend Architecture
- **Runtime:** Node.js version
- **Framework:** Express, Fastify, NestJS
- **API Design:** REST, GraphQL, tRPC
- **Authentication:** JWT, OAuth, Sessions
- **Authorization:** RBAC, ABAC
- **Middleware:** Security, logging, error handling
- **Background Jobs:** Bull, BullMQ (if needed)

### 4. Database Design
- **Database Choice:** PostgreSQL, MongoDB, etc with reasoning
- **ORM:** Prisma, TypeORM, Mongoose
- **Schema Design:** Entity relationships
- **Indexes:** Performance-critical indexes
- **Migrations:** Strategy and tooling
- **Backup:** Frequency and retention

### 5. API Design
- **Versioning:** URL-based (/api/v1/)
- **Request/Response:** JSON schemas
- **Error Handling:** Standardized format
- **Pagination:** Cursor or offset
- **Rate Limiting:** Strategy and limits
- **Documentation:** OpenAPI/Swagger

### 6. Non-Functional Requirements
- **Performance Targets:** Response time, page load
- **Security:** Authentication, encryption, OWASP
- **Scalability:** Horizontal scaling approach
- **Reliability:** Uptime, error rates
- **Monitoring:** Logging, APM, error tracking

### 7. Infrastructure
- **Hosting:** Vercel, AWS, Railway, etc
- **CI/CD:** GitHub Actions, GitLab CI
- **Environments:** Dev, Staging, Production
- **Secrets Management:** Environment variables, vaults

### 8. Development Standards
- **TypeScript:** tsconfig.json settings
- **Linting:** ESLint configuration
- **Testing:** Frameworks and coverage goals
- **Git:** Branch strategy, commit conventions

## Best Practices

### Keep It Practical
- Document decisions, not obvious choices
- Focus on "why" not just "what"
- Include diagrams for complex systems
- Keep it maintainable and up-to-date

### Make It Actionable
- Clear enough for developers to implement
- Specific technology versions
- Configuration examples
- Code snippets for patterns

### Use Architecture Decision Records (ADRs)
For each major decision:
- **Context:** What problem does this solve?
- **Decision:** What did we choose?
- **Consequences:** What are the trade-offs?

## Validation
Use `checklists/architecture-review-checklist.md` to validate completeness

## Handoff
Once complete:
1. Review with team
2. Get stakeholder approval
3. Save to `docs/architecture/`
4. Use as basis for story creation