112 lines
3.6 KiB
Markdown
112 lines
3.6 KiB
Markdown
# <!-- 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 |