[[LLM: If available, review any provided relevant documents to gather all relevant context before beginning. At minimum, you should have access to docs/prd.md and docs/front-end-spec.md. Ask the user for any documents you need but cannot locate. This template creates a unified architecture that covers both backend and frontend concerns to guide AI-driven fullstack development.]]
## Introduction
[[LLM: This section establishes the document's purpose and scope. Keep the content below but ensure project name is properly substituted.
After presenting this section, apply `tasks#advanced-elicitation` protocol]]
This document outlines the complete fullstack architecture for {{Project Name}}, including backend systems, frontend implementation, and their integration. It serves as the single source of truth for AI-driven development, ensuring consistency across the entire technology stack.
This unified approach combines what would traditionally be separate backend and frontend architecture documents, streamlining the development process for modern fullstack applications where these concerns are increasingly intertwined.
### Starter Template or Existing Project
[[LLM: Before proceeding with architecture design, check if the project is based on any starter templates or existing codebases:
1. Review the PRD and other documents for mentions of:
[[LLM: This section contains multiple subsections that establish the foundation. Present all subsections together, then apply `tasks#advanced-elicitation` protocol to the complete section.]]
### Technical Summary
[[LLM: Provide a comprehensive overview (4-6 sentences) covering:
- Overall architectural style and deployment approach
- Frontend framework and backend technology choices
- Key integration points between frontend and backend
- Infrastructure platform and services
- How this architecture achieves PRD goals]]
### Platform and Infrastructure Choice
[[LLM: Based on PRD requirements and technical assumptions, make a platform recommendation:
1. Consider common patterns (not an exhaustive list, use your own best judgement and search the web as needed for emerging trends):
- **Vercel + Supabase**: For rapid development with Next.js, built-in auth/storage
- **AWS Full Stack**: For enterprise scale with Lambda, API Gateway, S3, Cognito
- **Azure**: For .NET ecosystems or enterprise Microsoft environments
- **Google Cloud**: For ML/AI heavy applications or Google ecosystem integration
2. Present 2-3 viable options with clear pros/cons
3. Make a recommendation with rationale
4. Get explicit user confirmation
Document the choice and key services that will be used.]]
**Platform:** {{selected_platform}}
**Key Services:** {{core_services_list}}
**Deployment Host and Regions:** {{regions}}
### Repository Structure
[[LLM: Define the repository approach based on PRD requirements and platform choice:
1. For modern fullstack apps, monorepo is often preferred
- **Jamstack Architecture:** Static site generation with serverless APIs - _Rationale:_ Optimal performance and scalability for content-heavy applications
- **Component-Based UI:** Reusable React components with TypeScript - _Rationale:_ Maintainability and type safety across large codebases
- **Repository Pattern:** Abstract data access logic - _Rationale:_ Enables testing and future database migration flexibility
- **API Gateway Pattern:** Single entry point for all API calls - _Rationale:_ Centralized auth, rate limiting, and monitoring
@{/example}
## Tech Stack
[[LLM: This is the DEFINITIVE technology selection for the entire project. Work with user to finalize all choices. This table is the single source of truth - all development must use these exact versions.
Key areas to cover:
- Frontend and backend languages/frameworks
- Databases and caching
- Authentication and authorization
- API approach
- Testing tools for both frontend and backend
- Build and deployment tools
- Monitoring and logging
Upon render, apply `tasks#advanced-elicitation` display immediately.]]
- **Purpose:** Payment processing and subscription management
- **Documentation:** https://stripe.com/docs/api
- **Base URL(s):** `https://api.stripe.com/v1`
- **Authentication:** Bearer token with secret key
- **Rate Limits:** 100 requests per second
**Key Endpoints Used:**
-`POST /customers` - Create customer profiles
-`POST /payment_intents` - Process payments
-`POST /subscriptions` - Manage subscriptions
@{/example}
^^/CONDITION: has_external_apis^^
[[LLM: After presenting external APIs (or noting their absence), apply `tasks#advanced-elicitation` protocol]]
## Core Workflows
[[LLM: Illustrate key system workflows using sequence diagrams:
1. Identify critical user journeys from PRD
2. Show component interactions including external APIs
3. Include both frontend and backend flows
4. Include error handling paths
5. Document async operations
6. Create both high-level and detailed diagrams as needed
Focus on workflows that clarify architecture decisions or complex interactions.
After presenting the workflow diagrams, apply `tasks#advanced-elicitation` protocol]]
## Database Schema
[[LLM: Transform the conceptual data models into concrete database schemas:
1. Use the database type(s) selected in Tech Stack
2. Create schema definitions using appropriate notation
3. Include indexes, constraints, and relationships
4. Consider performance and scalability
5. For NoSQL, show document structures
Present schema in format appropriate to database type (SQL DDL, JSON schema, etc.)
After presenting the database schema, apply `tasks#advanced-elicitation` protocol]]
## Frontend Architecture
[[LLM: Define frontend-specific architecture details. After each subsection, note if user wants to refine before continuing.
After presenting this section, apply `tasks#advanced-elicitation` protocol]]
### Component Architecture
[[LLM: Define component organization and patterns based on chosen framework.]]
**Component Organization:**
```
{{component_structure}}
```
**Component Template:**
```typescript
{
{
component_template;
}
}
```
### State Management Architecture
[[LLM: Detail state management approach based on chosen solution.]]
**State Structure:**
```typescript
{
{
state_structure;
}
}
```
**State Management Patterns:**
- {{pattern_1}}
- {{pattern_2}}
### Routing Architecture
[[LLM: Define routing structure based on framework choice.]]
**Route Organization:**
```
{{route_structure}}
```
**Protected Route Pattern:**
```typescript
{
{
protected_route_example;
}
}
```
### Frontend Services Layer
[[LLM: Define how frontend communicates with backend.]]
**API Client Setup:**
```typescript
{
{
api_client_setup;
}
}
```
**Service Example:**
```typescript
{
{
service_example;
}
}
```
## Backend Architecture
[[LLM: Define backend-specific architecture details. Consider serverless vs traditional server approaches.
After presenting this section, apply `tasks#advanced-elicitation` protocol]]
### Service Architecture
[[LLM: Based on platform choice, define service organization.]]
^^CONDITION: serverless^^
**Function Organization:**
```
{{function_structure}}
```
**Function Template:**
```typescript
{
{
function_template;
}
}
```
^^/CONDITION: serverless^^
^^CONDITION: traditional_server^^
**Controller/Route Organization:**
```
{{controller_structure}}
```
**Controller Template:**
```typescript
{
{
controller_template;
}
}
```
^^/CONDITION: traditional_server^^
### Database Architecture
[[LLM: Define database schema and access patterns.]]
**Schema Design:**
```sql
{{database_schema}}
```
**Data Access Layer:**
```typescript
{
{
repository_pattern;
}
}
```
### Authentication and Authorization
[[LLM: Define auth implementation details.]]
**Auth Flow:**
```mermaid
{{auth_flow_diagram}}
```
**Middleware/Guards:**
```typescript
{
{
auth_middleware;
}
}
```
## Unified Project Structure
[[LLM: Create a monorepo structure that accommodates both frontend and backend. Adapt based on chosen tools and frameworks. After presenting, apply `tasks#advanced-elicitation` protocol.]]
```plaintext
{{project-name}}/
├── .github/ # CI/CD workflows
│ └── workflows/
│ ├── ci.yml
│ └── deploy.yml
├── apps/ # Application packages
│ ├── web/ # Frontend application
│ │ ├── src/
│ │ │ ├── components/ # UI components
│ │ │ ├── pages/ # Page components/routes
│ │ │ ├── hooks/ # Custom React hooks
│ │ │ ├── services/ # API client services
│ │ │ ├── stores/ # State management
│ │ │ ├── styles/ # Global styles/themes
│ │ │ └── utils/ # Frontend utilities
│ │ ├── public/ # Static assets
│ │ ├── tests/ # Frontend tests
│ │ └── package.json
│ └── api/ # Backend application
│ ├── src/
│ │ ├── routes/ # API routes/controllers
│ │ ├── services/ # Business logic
│ │ ├── models/ # Data models
│ │ ├── middleware/ # Express/API middleware
│ │ ├── utils/ # Backend utilities
│ │ └── {{serverless_or_server_entry}}
│ ├── tests/ # Backend tests
│ └── package.json
├── packages/ # Shared packages
│ ├── shared/ # Shared types/utilities
│ │ ├── src/
│ │ │ ├── types/ # TypeScript interfaces
│ │ │ ├── constants/ # Shared constants
│ │ │ └── utils/ # Shared utilities
│ │ └── package.json
│ ├── ui/ # Shared UI components
│ │ ├── src/
│ │ └── package.json
│ └── config/ # Shared configuration
│ ├── eslint/
│ ├── typescript/
│ └── jest/
├── infrastructure/ # IaC definitions
│ └── {{iac_structure}}
├── scripts/ # Build/deploy scripts
├── docs/ # Documentation
│ ├── prd.md
│ ├── front-end-spec.md
│ └── fullstack-architecture.md
├── .env.example # Environment template
├── package.json # Root package.json
├── {{monorepo_config}} # Monorepo configuration
└── README.md
```
@{example: vercel_structure}
apps/
├── web/ # Next.js app
│ ├── app/ # App directory (Next.js 14+)
│ ├── components/
│ └── lib/
└── api/ # API routes in Next.js or separate
└── pages/api/ # API routes
@{/example}
## Development Workflow
[[LLM: Define the development setup and workflow for the fullstack application.
After presenting this section, apply `tasks#advanced-elicitation` protocol]]
### Local Development Setup
**Prerequisites:**
```bash
{{prerequisites_commands}}
```
**Initial Setup:**
```bash
{{setup_commands}}
```
**Development Commands:**
```bash
# Start all services
{{start_all_command}}
# Start frontend only
{{start_frontend_command}}
# Start backend only
{{start_backend_command}}
# Run tests
{{test_commands}}
```
### Environment Configuration
**Required Environment Variables:**
```bash
# Frontend (.env.local)
{{frontend_env_vars}}
# Backend (.env)
{{backend_env_vars}}
# Shared
{{shared_env_vars}}
```
## Deployment Architecture
[[LLM: Define deployment strategy based on platform choice. After presenting, apply `tasks#advanced-elicitation` protocol.]]
| Production | {{prod_fe_url}} | {{prod_be_url}} | Live environment |
## Security and Performance
[[LLM: Define security and performance considerations for the fullstack application.
After presenting this section, apply `tasks#advanced-elicitation` protocol]]
### Security Requirements
**Frontend Security:**
- CSP Headers: {{csp_policy}}
- XSS Prevention: {{xss_strategy}}
- Secure Storage: {{storage_strategy}}
**Backend Security:**
- Input Validation: {{validation_approach}}
- Rate Limiting: {{rate_limit_config}}
- CORS Policy: {{cors_config}}
**Authentication Security:**
- Token Storage: {{token_strategy}}
- Session Management: {{session_approach}}
- Password Policy: {{password_requirements}}
### Performance Optimization
**Frontend Performance:**
- Bundle Size Target: {{bundle_size}}
- Loading Strategy: {{loading_approach}}
- Caching Strategy: {{fe_cache_strategy}}
**Backend Performance:**
- Response Time Target: {{response_target}}
- Database Optimization: {{db_optimization}}
- Caching Strategy: {{be_cache_strategy}}
## Testing Strategy
[[LLM: Define comprehensive testing approach for fullstack application.
After presenting this section, apply `tasks#advanced-elicitation` protocol]]
### Testing Pyramid
```
E2E Tests
/ \
Integration Tests
/ \
Frontend Unit Backend Unit
```
### Test Organization
**Frontend Tests:**
```
{{frontend_test_structure}}
```
**Backend Tests:**
```
{{backend_test_structure}}
```
**E2E Tests:**
```
{{e2e_test_structure}}
```
### Test Examples
**Frontend Component Test:**
```typescript
{
{
frontend_test_example;
}
}
```
**Backend API Test:**
```typescript
{
{
backend_test_example;
}
}
```
**E2E Test:**
```typescript
{
{
e2e_test_example;
}
}
```
## Coding Standards
[[LLM: Define MINIMAL but CRITICAL standards for AI agents. Focus only on project-specific rules that prevent common mistakes. These will be used by dev agents.
After presenting this section, apply `tasks#advanced-elicitation` protocol]]
### Critical Fullstack Rules
<<REPEAT:critical_rule>>
- **{{rule_name}}:** {{rule_description}}
<</REPEAT>>
@{example: critical_rules}
- **Type Sharing:** Always define types in packages/shared and import from there
- **API Calls:** Never make direct HTTP calls - use the service layer
- **Environment Variables:** Access only through config objects, never process.env directly
- **Error Handling:** All API routes must use the standard error handler
- **State Updates:** Never mutate state directly - use proper state management patterns
[[LLM: Before running the checklist, offer to output the full architecture document. Once user confirms, execute the `architect-checklist` and populate results here.]]
## Next Steps
[[LLM: Provide specific next steps for implementation.]]
### Implementation Order
1.**Environment Setup**
- Initialize monorepo structure
- Configure development environment
- Set up version control
2.**Foundation (Epic 1)**
- Implement authentication flow
- Set up database schema
- Create basic API structure
- Implement core UI components
3.**Feature Development**
- Follow story sequence from PRD
- Maintain type safety across stack
- Write tests as you go
### Developer Handoff Prompts
**For Scrum Master:**
"Create stories for {{Project Name}} using the PRD at docs/prd.md and this fullstack architecture at docs/fullstack-architecture.md. Focus on Epic 1 implementation."
**For Developer:**
"Implement Story 1.1 from docs/stories/epic1/story-1.1.md using the fullstack architecture at docs/fullstack-architecture.md. Follow the coding standards and use the defined tech stack."
