ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

moved some files around

Browse Source
This commit is contained in:
Brian Madison
2025-05-11 20:34:33 -05:00
parent 70d551ab14
commit 383f49c759
42 changed files with 400 additions and 1871 deletions
Download Patch File Download Diff File Expand all files Collapse all files

267
BETA-V3/templates/architecture-tmpl.txt Normal file
View File

@@ -0,0 +1,267 @@
# {Project Name} Architecture Document
## Table of Contents
{ Update this if sections and subsections are added or removed }
- [Technical Summary](#technical-summary)
- [High-Level Overview](#high-level-overview)
- [Component View](#component-view)
- [Architectural / Design Patterns Adopted](#architectural--design-patterns-adopted)
- [API Reference](#api-reference)
- [External APIs Consumed](#external-apis-consumed)
- [{Another External Service Name} API](#another-external-service-name-api)
- [Internal APIs Provided (If Applicable)](#internal-apis-provided-if-applicable)
- [Data Models](#data-models)
- [Core Application Entities / Domain Objects](#core-application-entities--domain-objects)
- [API Payload Schemas (If distinct)](#api-payload-schemas-if-distinct)
- [Database Schemas (If applicable)](#database-schemas-if-applicable)
- [State File Schemas (If applicable)](#state-file-schemas-if-applicable)
- [Core Workflow / Sequence Diagrams](#core-workflow--sequence-diagrams)
- [Definitive Tech Stack Selections](#definitive-tech-stack-selections)
- [Infrastructure and Deployment Overview](#infrastructure-and-deployment-overview)
- [Error Handling Strategy](#error-handling-strategy)
- [Environment Vars Templates](#environment-vars-templates)
- [Configuration Loading Mechanism](#configuration-loading-mechanism)
- [Required Variables](#required-variables)
- [Env Var Notes](#env-var-notes)
- [Security Best Practices](#security-best-practices)
- [Testing Strategy](#testing-strategy)
- [Overall Philosophy & Goals](#overall-philosophy--goals)
- [Testing Levels](#testing-levels)
- [Specialized Testing Types (Add section as needed)](#specialized-testing-types-add-section-as-needed)
- [Test Data Management](#test-data-management)
- [Key Reference Documents](#key-reference-documents)
- [Change Log](#change-log)
## Technical Summary
{ Provide a brief paragraph overview of the system's architecture, key components, technology choices, and architectural patterns used. Reference the goals from the PRD. }
## High-Level Overview
{ Describe the main architectural style (e.g., Monolith, Microservices, Serverless, Event-Driven), reflecting the decision made in the PRD. Explain the repository structure (Monorepo/Polyrepo). Explain the primary user interaction or data flow at a conceptual level. }
{ Insert high-level mermaid system context or interaction diagram here - e.g., Mermaid Class C4 Models Layer 1 and 2 }
## Component View
{ Describe the major logical components or services of the system and their responsibilities, reflecting the decided overall architecture (e.g., distinct microservices, modules within a monolith, packages within a monorepo). Explain how they collaborate. }
- Component A: {Description of responsibility}
{Insert component diagram here if it helps - e.g., using Mermaid graph TD or C4 Model Container/Component Diagram}
- Component N...: {Description of responsibility}
{ Insert component diagram here if it helps - e.g., using Mermaid graph TD or C4 Model Container/Component Diagram }
### Architectural / Design Patterns Adopted
{ List the key high-level patterns chosen in the architecture document. These foundational patterns should be established early as they guide component design, interactions, and technology choices. }
- **Pattern 1:** {e.g., Serverless, Event-Driven, Microservices, CQRS} - _Rationale/Reference:_ {Briefly why, or link to a more detailed explanation if needed}
- **Pattern 2:** {e.g., Dependency Injection, Repository Pattern, Module Pattern} - _Rationale/Reference:_ {...}
- **Pattern N:** {...}
## API Reference
### External APIs Consumed
{Repeat this section for each external API the system interacts with.}
#### {External Service Name} API
- **Purpose:** {Why does the system use this API?}
- **Base URL(s):**
- Production: `{URL}`
- Staging/Dev: `{URL}`
- **Authentication:** {Describe method - e.g., API Key in Header (Header Name: `X-API-Key`), OAuth 2.0 Client Credentials, Basic Auth. Reference `docs/environment-vars.md` for key names.}
- **Key Endpoints Used:**
- **`{HTTP Method} {/path/to/endpoint}`:**
- Description: {What does this endpoint do?}
- Request Parameters: {Query params, path params}
- Request Body Schema: {Provide JSON schema inline, or link to a detailed definition in `docs/data-models.md` only if the schema is exceptionally large or complex.}
- Example Request: `{Code block}`
- Success Response Schema (Code: `200 OK`): {Provide JSON schema inline, or link to a detailed definition in `docs/data-models.md` only if very complex.}
- Error Response Schema(s) (Codes: `4xx`, `5xx`): {Provide JSON schema inline, or link to a detailed definition in `docs/data-models.md` only if very complex.}
- Example Response: `{Code block}`
- **`{HTTP Method} {/another/endpoint}`:** {...}
- **Rate Limits:** {If known}
- **Link to Official Docs:** {URL}
### {Another External Service Name} API
{...}
### Internal APIs Provided (If Applicable)
{If the system exposes its own APIs (e.g., in a microservices architecture or for a UI frontend). Repeat for each API.}
#### {Internal API / Service Name} API
- **Purpose:** {What service does this API provide?}
- **Base URL(s):** {e.g., `/api/v1/...`}
- **Authentication/Authorization:** {Describe how access is controlled.}
- **Endpoints:**
- **`{HTTP Method} {/path/to/endpoint}`:**
- Description: {What does this endpoint do?}
- Request Parameters: {...}
- Request Body Schema: {Provide JSON schema inline, or link to a detailed definition in `docs/data-models.md` only if very complex.}
- Success Response Schema (Code: `200 OK`): {Provide JSON schema inline, or link to a detailed definition in `docs/data-models.md` only if very complex.}
- Error Response Schema(s) (Codes: `4xx`, `5xx`): {Provide JSON schema inline, or link to a detailed definition in `docs/data-models.md` only if very complex.}
- **`{HTTP Method} {/another/endpoint}`:** {...}
## Data Models
### Core Application Entities / Domain Objects
{Define the main objects/concepts the application works with. Repeat subsection for each key entity.}
#### {Entity Name, e.g., User, Order, Product}
- **Description:** {What does this entity represent?}
- **Schema / Interface Definition:**
```typescript
// Example using TypeScript Interface
export interface {EntityName} {
id: string; // {Description, e.g., Unique identifier}
propertyName: string; // {Description}
optionalProperty?: number; // {Description}
// ... other properties
}
```
_(Alternatively, use JSON Schema, class definitions, or other relevant format)_
- **Validation Rules:** {List any specific validation rules beyond basic types - e.g., max length, format, range.}
#### {Another Entity Name}
{...}
### API Payload Schemas (If distinct)
{Define schemas here only if they are distinct from core entities AND not fully detailed under the API endpoint definitions in the API Reference section. Prefer detailing request/response schemas directly with their APIs where possible. This section is for complex, reusable payload structures that might be used across multiple internal APIs or differ significantly from core persisted entities.}
#### {API Endpoint / Purpose, e.g., Create Order Request}
- **Schema / Interface Definition:**
```typescript
// Example
export interface CreateOrderRequest {
customerId: string;
items: { productId: string; quantity: number }[];
// ...
}
```
#### {Another API Payload}
{...}
### Database Schemas (If applicable)
{If using a database, define table structures or document database schemas.}
#### {Table / Collection Name}
- **Purpose:** {What data does this table store?}
- **Schema Definition:**
```sql
-- Example SQL
CREATE TABLE {TableName} (
id VARCHAR(36) PRIMARY KEY,
column_name VARCHAR(255) NOT NULL,
numeric_column DECIMAL(10, 2),
-- ... other columns, indexes, constraints
);
```
_(Alternatively, use ORM model definitions, NoSQL document structure, etc.)_
#### {Another Table / Collection Name}
{...}
### State File Schemas (If applicable)
{If the application uses files for persisting state.}
#### {State File Name / Purpose, e.g., processed_items.json}
- **Purpose:** {What state does this file track?}
- **Format:** {e.g., JSON}
- **Schema Definition:**
```json
{
"type": "object",
"properties": {
"processedIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of IDs that have been processed."
}
// ... other state properties
},
"required": ["processedIds"]
}
```
## Core Workflow / Sequence Diagrams
{ Illustrate key or complex workflows using mermaid sequence diagrams. Can have high level tying the full project together, and also smaller epic level sequence diagrams. }
## Definitive Tech Stack Selections
{ This section outlines the definitive technology choices for the project. These selections should be made after a thorough understanding of the project's requirements, components, data models, and core workflows. The Architect Agent should guide the user through these decisions, ensuring each choice is justified and recorded accurately in the table below.
Key decisions to discuss and finalize here, which will then be expanded upon and formally documented in the detailed stack table below, include considerations such as:
- Preferred Starter Template Frontend: { Url to template or starter, if used }
- Preferred Starter Template Backend: { Url to template or starter, if used }
- Primary Language(s) & Version(s): {e.g., TypeScript 5.x, Python 3.11}
- Primary Runtime(s) & Version(s): {e.g., Node.js 22.x}
Must be definitive selections; do not list open-ended choices (e.g., for web scraping, pick one tool, not two). Specify versions or clearly state "Latest," but be cautious with "Latest" if dependency issues are a concern. }
| Category | Technology | Version / Details | Description / Purpose | Justification (Optional) |
| :------------------- | :---------------------- | :---------------- | :-------------------------------------- | :----------------------- |
| **Languages** | {e.g., TypeScript} | {e.g., 5.x} | {Primary language for backend/frontend} | {Why this language?} |
| | {e.g., Python} | {e.g., 3.11} | {Used for data processing, ML} | {...} |
| **Runtime** | {e.g., Node.js} | {e.g., 22.x} | {Server-side execution environment} | {...} |
| **Frameworks** | {e.g., NestJS} | {e.g., 10.x} | {Backend API framework} | {Why this framework?} |
| | {e.g., React} | {e.g., 18.x} | {Frontend UI library} | {...} |
| **Databases** | {e.g., PostgreSQL} | {e.g., 15} | {Primary relational data store} | {...} |
| | {e.g., Redis} | {e.g., 7.x} | {Caching, session storage} | {...} |
| **Cloud Platform** | {e.g., AWS} | {N/A} | {Primary cloud provider} | {...} |
| **Cloud Services** | {e.g., AWS Lambda} | {N/A} | {Serverless compute} | {...} |
| | {e.g., AWS S3} | {N/A} | {Object storage for assets/state} | {...} |
| | {e.g., AWS EventBridge} | {N/A} | {Event bus / scheduled tasks} | {...} |
| **Infrastructure** | {e.g., AWS CDK} | {e.g., Latest} | {Infrastructure as Code tool} | {...} |
| | {e.g., Docker} | {e.g., Latest} | {Containerization} | {...} |
| **UI Libraries** | {e.g., Material UI} | {e.g., 5.x} | {React component library} | {...} |
| **State Management** | {e.g., Redux Toolkit} | {e.g., Latest} | {Frontend state management} | {...} |
| **Testing** | {e.g., Jest} | {e.g., Latest} | {Unit/Integration testing framework} | {...} |
| | {e.g., Playwright} | {e.g., Latest} | {End-to-end testing framework} | {...} |
| **CI/CD** | {e.g., GitHub Actions} | {N/A} | {Continuous Integration/Deployment} | {...} |
| **Other Tools** | {e.g., LangChain.js} | {e.g., Latest} | {LLM interaction library} | {...} |
| | {e.g., Cheerio} | {e.g., Latest} | {HTML parsing/scraping} | {...} |
## Infrastructure and Deployment Overview
- Cloud Provider(s): {e.g., AWS, Azure, GCP, On-premise}
- Core Services Used: {List key managed services - e.g., Lambda, S3, Kubernetes Engine, RDS, Kafka}
- Infrastructure as Code (IaC): {Tool used - e.g., AWS CDK, Terraform...} - Location: {Link to IaC code repo/directory}
- Deployment Strategy: {e.g., CI/CD pipeline, Manual deployment steps, Blue/Green, Canary} - Tools: {e.g., Jenkins, GitHub Actions, GitLab CI}
- Environments: {List environments - e.g., Development, Staging, Production}
## Error Handling Strategy
- **General Approach:** {e.g., Use exceptions, return error codes/tuples, specific error types.}
- **Logging:**
- Library/Method: {e.g., `console.log/error`, Python `logging` module, dedicated logging library}
- Format: {e.g., JSON, plain text}
- Levels: {e.g., DEBUG, INFO, WARN, ERROR}
- Context: {What contextual information should be included?}
- **Specific Handling Patterns:**
- External API Calls: {e.g., Use `

345
BETA-V3/templates/front-end-architecture-tmpl.txt Normal file
View File

@@ -0,0 +1,345 @@
# {Project Name} Frontend Architecture Document
## Table of Contents
{ Update this if sections and subsections are added or removed }
- [Introduction](#introduction)
- [Overall Frontend Philosophy & Patterns](#overall-frontend-philosophy--patterns)
- [Detailed Frontend Directory Structure](#detailed-frontend-directory-structure)
- [Component Breakdown & Implementation Details](#component-breakdown--implementation-details)
- [Component Naming & Organization](#component-naming--organization)
- [Template for Component Specification](#template-for-component-specification)
- [State Management In-Depth](#state-management-in-depth)
- [Store Structure / Slices](#store-structure--slices)
- [Key Selectors](#key-selectors)
- [Key Actions / Reducers / Thunks](#key-actions--reducers--thunks)
- [API Interaction Layer](#api-interaction-layer)
- [Client/Service Structure](#clientservice-structure)
- [Error Handling & Retries (Frontend)](#error-handling--retries-frontend)
- [Routing Strategy](#routing-strategy)
- [Route Definitions](#route-definitions)
- [Route Guards / Protection](#route-guards--protection)
- [Build, Bundling, and Deployment](#build-bundling-and-deployment)
- [Build Process & Scripts](#build-process--scripts)
- [Key Bundling Optimizations](#key-bundling-optimizations)
- [Deployment to CDN/Hosting](#deployment-to-cdnhosting)
- [Frontend Testing Strategy](#frontend-testing-strategy)
- [Component Testing](#component-testing)
- [UI Integration/Flow Testing](#ui-integrationflow-testing)
- [End-to-End UI Testing Tools & Scope](#end-to-end-ui-testing-tools--scope)
- [Accessibility (AX) Implementation Details](#accessibility-ax-implementation-details)
- [Performance Considerations](#performance-considerations)
- [Change Log](#change-log)
## Introduction
{ This document details the technical architecture specifically for the frontend of {Project Name}. It complements the main {Project Name} Architecture Document and the UI/UX Specification. The goal is to provide a clear blueprint for frontend development, ensuring consistency, maintainability, and alignment with the overall system design and user experience goals. }
- **Link to Main Architecture Document:** {e.g., `docs/architecture.md`} (Note: The overall system architecture, including Monorepo/Polyrepo decisions and backend structure, will influence frontend choices, especially around shared code or API interaction patterns.)
- **Link to UI/UX Specification:** {e.g., `docs/front-end-spec.md`}
- **Link to Primary Design Files (Figma, Sketch, etc.):** {From UI/UX Spec}
- **Link to Deployed Storybook / Component Showcase (if applicable):** {URL}
## Overall Frontend Philosophy & Patterns
{ Describe the core architectural decisions and patterns chosen for the frontend. This should align with the "Definitive Tech Stack Selections" in the main architecture document and consider implications from the overall system architecture (e.g., monorepo vs. polyrepo, backend service structure). }
- **Framework & Core Libraries:** {e.g., React 18.x with Next.js 13.x, Angular 16.x, Vue 3.x with Nuxt.js. Briefly reiterate why these were chosen if not detailed enough in the main arch doc.}
- **Component Architecture:** {e.g., Atomic Design principles, Presentational vs. Container components, use of specific component libraries like Material UI, Tailwind CSS for styling approach.}
- **State Management Strategy:** {e.g., Redux Toolkit, Zustand, Vuex, NgRx. Briefly describe the overall approach – global store, feature stores, context API usage. More details in "State Management In-Depth" section.}
- **Data Flow:** {e.g., Unidirectional data flow, how data is fetched, passed to components, and updated.}
- **Styling Approach:** {e.g., CSS Modules, Styled Components, SCSS with BEM, Tailwind CSS. Link to configuration if applicable.}
- **Key Design Patterns Used:** {e.g., Provider pattern, Hooks, Higher-Order Components, Service patterns for API calls.}
## Detailed Frontend Directory Structure
{ Provide an ASCII diagram representing the frontend application\'s specific folder structure (e.g., within `src/` or `app/`). This should elaborate on the frontend part of the main project structure outlined in the architecture document. Highlight conventions for organizing components, pages/views, services, state, styles, assets, etc. }
### EXAMPLE - Not Prescriptive (for a React/Next.js app)
```plaintext
src/
├── app/ # Next.js App Router: Pages/Layouts/Routes
│ ├── (features)/ # Feature-based routing groups
│ │ └── dashboard/
│ │ ├── layout.tsx
│ │ └── page.tsx
│ ├── api/ # API Routes (if using Next.js backend features)
│ ├── globals.css
│ └── layout.tsx # Root layout
├── components/ # Shared/Reusable UI Components
│ ├── ui/ # Base UI elements (Button, Input, Card - often from a library)
│ │ ├── Button.tsx
│ │ └── ...
│ ├── layout/ # Layout components (Header, Footer, Sidebar)
│ │ ├── Header.tsx
│ │ └── ...
│ └── (feature-specific)/ # Components specific to a feature but potentially reusable within it
│ └── user-profile/
│ └── ProfileCard.tsx
├── features/ # Feature-specific logic, hooks, non-global state, services
│ └── auth/
│ ├── components/ # Components used only by the auth feature
│ ├── hooks/ # Feature-specific hooks
│ ├── services/ # Feature-specific API interactions
│ └── store.ts # Feature-specific state slice (if applicable)
├── hooks/ # Global/sharable custom hooks
│ └── useAuth.ts
├── lib/ # Utility functions, helpers, constants
│ └── utils.ts
├── services/ # Global API service clients or SDK configurations
│ └── apiClient.ts
├── store/ # Global state management (e.g., Redux store setup)
│ ├── index.ts
│ ├── rootReducer.ts
│ └── (slices)/
├── styles/ # Global styles, theme configurations (if not using `globals.css` or similar)
└── types/ # Global TypeScript type definitions
└── index.ts
```
### Notes on Frontend Structure:
{ Explain any specific conventions or rationale behind the structure. For example, "Components are co-located with their feature if not globally reusable." }
## Component Breakdown & Implementation Details
{ This section outlines the conventions and templates for defining UI components. While a few globally shared or foundational components (e.g., core UI elements if not from a library, main layout structures) might be specified here upfront to ensure consistency, the detailed specification for most feature-specific components will emerge as user stories are implemented. The key is for the development team (or AI agent) to follow the "Template for Component Specification" below whenever a new component is identified for development. }
### Component Naming & Organization
{ Briefly describe conventions for naming components (e.g., PascalCase, `feature-ComponentName.tsx`). How are components organized on the filesystem (reiterate from directory structure if needed)? Are components grouped by feature, type (UI, layout), etc.? }
### Template for Component Specification
{ For each significant UI component identified from the UI/UX Specification and design files (Figma), provide the following details. Repeat this subsection for each component. The level of detail should be sufficient for an AI agent or developer to implement it with minimal ambiguity. }
#### Component: `{ComponentName}` (e.g., `UserProfileCard`, `ProductDetailsView`)
- **Purpose:** {Briefly describe what this component does and its role in the UI.}
- **Source File(s):** {e.g., `src/components/user-profile/UserProfileCard.tsx`}
- **Visual Reference:** {Link to specific Figma frame/component, or Storybook page.}
- **Props (Properties):**
{ List each prop the component accepts. }
| Prop Name | Type | Required? | Default Value | Description |
| :-------------- | :--------------------------- | :-------- | :------------ | :---------------------------------------------- |
| `userId` | `string` | Yes | N/A | The ID of the user to display. |
| `avatarUrl` | `string` | No | `null` | URL for the user\'s avatar image. |
| `onEdit` | `() => void` | No | N/A | Callback function when an edit action is triggered. |
| `variant` | `\'compact\' \| \'full\'` | No | `\'full\'` | Controls the display mode of the card. |
| `{anotherProp}` | `{type (e.g., number, boolean, customType)}` | {Yes/No} | {If any} | {Description} |
- **Internal State (if any):**
{ Describe any significant internal state the component manages. Minor UI state (e.g., `isDropdownOpen`) might not need explicit listing unless complex. }
| State Variable | Type | Initial Value | Description |
| :-------------- | :--------- | :------------ | :-------------------------------------------- |
| `isLoading` | `boolean` | `false` | Tracks if data for the component is loading. |
| `{anotherState}`| `{type}` | `{value}` | {Description} |
- **Key UI Elements / Structure:**
{ Describe the main visual parts of the component and their general layout. This can be a brief textual description or a very simple pseudo-HTML structure. }
```html
<div> <!-- Main card container -->
<img> <!-- Avatar -->
<h2> <!-- User Name -->
<p> <!-- User Email -->
<button> <!-- Edit Button (if applicable) -->
</div>
```
- **Events Handled / Emitted:**
- **Handles:** {e.g., `onClick` on the edit button.}
- **Emits:** {If the component emits custom events, describe them. e.g., `onFollow: (userId: string) => void`}
- **Actions Triggered (Side Effects):**
- **State Management:** {e.g., "Dispatches `fetchUserDetails(userId)` action on mount." "Calls `userSlice.actions.setUserName(newName)`."}
- **API Calls:** {Specify which service/function from the "API Interaction Layer" is called. e.g., "Calls `userService.fetchUser(userId)`." What data is passed? How is the response (success/error) handled? How does it update internal state or global state?}
- **Styling Notes:**
- {Reference to Design System components used (e.g., "Uses `<Button variant=\'primary\'>` from UI library").}
- {Key CSS classes to be applied (if using traditional CSS/SCSS/Tailwind directly).}
- {Specific responsiveness behavior if not covered globally.}
- **Accessibility Notes:**
- {Specific ARIA attributes needed (e.g., `aria-label`, `role`).}
- {Keyboard navigation considerations for this component.}
---
_Repeat the above template for each significant component._
---
## State Management In-Depth
{ This section expands on the State Management strategy chosen and outlined in the main architecture document and the "Overall Frontend Philosophy". It defines the conventions for how state modules should be structured and implemented. While the overall approach and core store setup (if any) are defined here, detailed state slices, selectors, and actions/thunks for specific features will generally be developed emergently as those features are built, adhering to these established patterns. }
- **Chosen Solution:** {e.g., Redux Toolkit, Zustand, Vuex, NgRx - reiterate from main arch doc.}
- **Rationale (briefly, if not fully covered in main arch doc):** {Why was this solution chosen over alternatives for this specific project?}
### Store Structure / Slices
{ Describe the conventions for organizing the global state (e.g., "Each major feature requiring global state will have its own Redux slice located in `src/features/[featureName]/store.ts`"). A few core, application-wide slices (e.g., for session management, theme) might be defined upfront as examples or foundational pieces. }
- **Core Slice Example (e.g., `sessionSlice`):**
- **Purpose:** {Manages user session, authentication status, and basic user profile info accessible globally.}
- **State Shape:**
```typescript
interface SessionState {
currentUser: {
id: string;
name: string;
email: string;
roles: string[];
} | null;
isAuthenticated: boolean;
token: string | null;
status: "idle" | "loading" | "succeeded" | "failed";
error: string | null;
}
```
- **Key Reducers/Actions:** {Briefly list main actions, e.g., `setSession`, `clearSession`, `authLoading`, `authSuccess`, `authFailure`.}
- **Feature Slice Template (e.g., `{featureName}Slice`):**
- **Purpose:** {To be filled out when a new feature requires its own state slice.}
- **State Shape:** {To be defined by the feature.}
- **Key Reducers/Actions:** {To be defined by the feature.}
### Key Selectors
{ List important selectors for any core, upfront slices. For emergent feature slices, selectors will be defined with the slice. Conventions for creating selectors should be noted (e.g., use `createSelector` for memoization). }
- **`selectCurrentUser`:** {Returns the `currentUser` object from `sessionSlice`.}
- **`selectIsAuthenticated`:** {Returns `isAuthenticated` boolean from `sessionSlice`.}
- **`selectAuthToken`:** {Returns the `token` from `sessionSlice`.}
### Key Actions / Reducers / Thunks
{ Detail more complex actions for core, upfront slices, especially asynchronous thunks or sagas. For emergent feature slices, these will be defined with the slice, following these patterns. }
- **Core Action/Thunk Example: `authenticateUser(credentials: AuthCredentials)`**
- **Purpose:** {Handles user login by calling the auth API and updating the `sessionSlice`.}
- **Dispatch Flow:**
1. Dispatches `sessionSlice.actions.setStatus('loading')`.
2. Calls `authService.login(credentials)` (from API Interaction Layer).
3. On success: Dispatches `sessionSlice.actions.setSession(response.data)` (which includes user and token) and `sessionSlice.actions.setStatus('succeeded')`.
4. On error: Dispatches `sessionSlice.actions.setError(error.message)` and `sessionSlice.actions.setStatus('failed')`.
- **Feature Action/Thunk Template: `{featureActionName}`**
- **Purpose:** {To be filled out for feature-specific async operations.}
- **Dispatch Flow:** {To be defined by the feature, following similar patterns.}
## API Interaction Layer
{ Describe how the frontend communicates with the backend APIs defined in the main Architecture Document. The focus here is on establishing the foundational client setup and patterns for creating service abstractions. Specific service functions will often emerge as features are developed. }
### Client/Service Structure
- **HTTP Client Setup:** {e.g., Axios instance, Fetch wrapper. Base URL configuration, default headers (e.g., for Authorization from state), interceptors for request/response handling (e.g., error normalization, token refresh).}
- **Service Definitions (Example):**
- **`userService.ts`:**
- **Purpose:** {Handles all API interactions related to users.}
- **Functions:**
- `fetchUser(userId: string): Promise<User>`
- `updateUserProfile(userId: string, data: UserProfileUpdateDto): Promise<User>`
- **`productService.ts`:**
- **Purpose:** {...}
- **Functions:** {...}
### Error Handling & Retries (Frontend)
- **Global Error Handling:** {How are API errors caught and presented to the user globally (e.g., toast notifications)? Is there a global error state?}
- **Specific Error Handling:** {How might components handle specific API errors for more contextual feedback?}
- **Retry Logic:** {Is there any client-side retry logic for idempotent requests? If so, how is it configured?}
## Routing Strategy
{ Detail how navigation and routing are handled in the frontend application. }
- **Routing Library:** {e.g., React Router, Next.js App Router, Vue Router, Angular Router.}
### Route Definitions
{ List the main routes of the application and the primary component rendered for each. }
| Path Pattern | Component/Page | Protection | Notes |
| :--------------------- | :---------------------------- | :------------ | :---------------------------------- |
| `/` | `HomePage.tsx` | Public | |
| `/login` | `LoginPage.tsx` | Public | Redirects if already authenticated. |
| `/dashboard` | `DashboardPage.tsx` | Authenticated | |
| `/products` | `ProductListPage.tsx` | Public | |
| `/products/:productId` | `ProductDetailsPage.tsx` | Public | |
| `/settings/profile` | `UserProfileSettingsPage.tsx` | Authenticated | |
| `{anotherRoute}` | `{Component}` | {Type} | {Notes} |
### Route Guards / Protection
- **Authentication Guard:** {Describe how routes are protected based on authentication status. e.g., A Higher-Order Component, a specific router hook.}
- **Authorization Guard (if applicable):** {Describe how routes might be protected based on user roles or permissions.}
## Build, Bundling, and Deployment
{ Details specific to the frontend build and deployment process, complementing the "Infrastructure and Deployment Overview" in the main architecture document. }
### Build Process & Scripts
- **Key Build Scripts:** {e.g., `npm run build`, `yarn build`. What do they do? Point to `package.json` scripts.}
- **Environment Variables Handling during Build:** {How are `process.env` variables (e.g., `NEXT_PUBLIC_API_URL`) managed for different environments (dev, staging, prod)?}
### Key Bundling Optimizations
- **Code Splitting:** {How is it implemented? e.g., Route-based, component-based using dynamic imports.}
- **Tree Shaking:** {Ensured by build tools?}
- **Lazy Loading:** {Strategy for lazy loading components, images, or routes.}
- **Minification & Compression:** {Handled by build tools (e.g., Webpack, Vite, Next.js build)?}
### Deployment to CDN/Hosting
- **Target Platform:** {e.g., Vercel, Netlify, AWS S3/CloudFront, Azure Static Web Apps.}
- **Deployment Trigger:** {e.g., Git push to main branch via GitHub Actions (referencing main CI/CD).}
- **Asset Caching Strategy:** {How are static assets cached by the CDN/browser?}
## Frontend Testing Strategy
{ This section elaborates on the "Testing Strategy" from the main architecture document, focusing on frontend-specific aspects. }
- **Link to Main Testing Strategy:** {Reference the main `docs/testing-strategy.md` or architecture doc section.}
### Component Testing
- **Scope:** {Testing individual UI components in isolation (similar to unit tests for components).}
- **Tools:** {e.g., React Testing Library, Jest, Vitest, Vue Test Utils, Angular Testing Utilities.}
- **Focus:** {Rendering, props handling, basic interactions, event emission, visual snapshot testing (optional).}
- **Location:** {e.g., `*.test.tsx` or `*.spec.tsx` alongside components.}
### UI Integration/Flow Testing
- **Scope:** {Testing how multiple components interact to fulfill a small user flow within a page or feature, potentially mocking API calls or state management.}
- **Tools:** {Same as component testing, but with more complex setups.}
- **Focus:** {Data flow between components, conditional rendering based on interactions, navigation within a feature.}
### End-to-End UI Testing Tools & Scope
- **Tools:** {Reiterate from main Testing Strategy, e.g., Playwright, Cypress, Selenium.}
- **Scope (Frontend Focus):** {Define key user journeys that will be covered by E2E UI tests. e.g., User registration, adding item to cart, completing checkout.}
- **Test Data Management for UI:** {How is consistent test data ensured for UI E2E tests?}
## Accessibility (AX) Implementation Details
{ Based on the AX requirements in the UI/UX Specification, detail how these will be technically implemented. }
- **Semantic HTML:** {Emphasis on using correct HTML5 elements.}
- **ARIA Implementation:** {Specific ARIA roles, states, and properties for custom/complex components.}
- **Keyboard Navigation:** {Ensuring all interactive elements are focusable and operable via keyboard.}
- **Focus Management:** {How is focus managed in modals, dynamic content changes?}
- **Testing Tools for AX:** {e.g., Axe DevTools, Lighthouse, manual testing procedures.}
## Performance Considerations
{ Highlight frontend-specific performance optimization strategies. }
- **Image Optimization:** {Formats (e.g., WebP), responsive images (`<picture>`, `srcset`), lazy loading.}
- **Code Splitting & Lazy Loading (reiterate from Build section if needed):** {How it impacts perceived performance.}
- **Minimizing Re-renders:** {Techniques like `React.memo`, `shouldComponentUpdate`, optimized selectors.}
- **Debouncing/Throttling:** {For event handlers like search input or window resize.}
- **Virtualization:** {For long lists or large data sets (e.g., React Virtualized, TanStack Virtual).}
- **Caching Strategies (Client-Side):** {Use of browser cache, service workers for PWA capabilities (if applicable).}
- **Performance Monitoring Tools:** {e.g., Lighthouse, WebPageTest, browser DevTools performance tab.}
## Change Log
| Change | Date | Version | Description | Author |
| ------ | ---- | ------- | ----------- | ------ |

84
BETA-V3/templates/front-end-spec-tmpl.txt Normal file
View File

@@ -0,0 +1,84 @@
# {Project Name} UI/UX Specification
## Introduction
{State the purpose - to define the user experience goals, information architecture, user flows, and visual design specifications for the project's user interface.}
- **Link to Primary Design Files:** {e.g., Figma, Sketch, Adobe XD URL}
- **Link to Deployed Storybook / Design System:** {URL, if applicable}
## Overall UX Goals & Principles
- **Target User Personas:** {Reference personas or briefly describe key user types and their goals.}
- **Usability Goals:** {e.g., Ease of learning, efficiency of use, error prevention.}
- **Design Principles:** {List 3-5 core principles guiding the UI/UX design - e.g., "Clarity over cleverness", "Consistency", "Provide feedback".}
## Information Architecture (IA)
- **Site Map / Screen Inventory:**
```mermaid
graph TD
A[Homepage] --> B(Dashboard);
A --> C{Settings};
B --> D[View Details];
C --> E[Profile Settings];
C --> F[Notification Settings];
```
_(Or provide a list of all screens/pages)_
- **Navigation Structure:** {Describe primary navigation (e.g., top bar, sidebar), secondary navigation, breadcrumbs, etc.}
## User Flows
{Detail key user tasks. Use diagrams or descriptions.}
### {User Flow Name, e.g., User Login}
- **Goal:** {What the user wants to achieve.}
- **Steps / Diagram:**
```mermaid
graph TD
Start --> EnterCredentials[Enter Email/Password];
EnterCredentials --> ClickLogin[Click Login Button];
ClickLogin --> CheckAuth{Auth OK?};
CheckAuth -- Yes --> Dashboard;
CheckAuth -- No --> ShowError[Show Error Message];
ShowError --> EnterCredentials;
```
_(Or: Link to specific flow diagram in Figma/Miro)_
### {Another User Flow Name}
{...}
## Wireframes & Mockups
{Reference the main design file link above. Optionally embed key mockups or describe main screen layouts.}
- **Screen / View Name 1:** {Description of layout and key elements. Link to specific Figma frame/page.}
- **Screen / View Name 2:** {...}
## Component Library / Design System Reference
## Branding & Style Guide Reference
{Link to the primary source or define key elements here.}
- **Color Palette:** {Primary, Secondary, Accent, Feedback colors (hex codes).}
- **Typography:** {Font families, sizes, weights for headings, body, etc.}
- **Iconography:** {Link to icon set, usage notes.}
- **Spacing & Grid:** {Define margins, padding, grid system rules.}
## Accessibility (AX) Requirements
- **Target Compliance:** {e.g., WCAG 2.1 AA}
- **Specific Requirements:** {Keyboard navigation patterns, ARIA landmarks/attributes for complex components, color contrast minimums.}
## Responsiveness
- **Breakpoints:** {Define pixel values for mobile, tablet, desktop, etc.}
- **Adaptation Strategy:** {Describe how layout and components adapt across breakpoints. Reference designs.}
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------------- | -------------- |

115
BETA-V3/templates/prd-tmpl.txt Normal file
View File

@@ -0,0 +1,115 @@
# {Project Name} Product Requirements Document (PRD)
## Goal, Objective and Context
Keep this brief and to the point in the final output - this should come mostly from the user or the provided brief, but ask for clarifications as needed.
## Functional Requirements (MVP)
You should have a good idea at this point, but clarify suggest question and explain to ensure these are correct.
## Non Functional Requirements (MVP)
## User Interaction and Design Goals
{
If the product includes a User Interface (UI), this section captures the Product Manager's high-level vision and goals for the User Experience (UX). This information will serve as a crucial starting point and brief for the Design Architect.
Consider and elicit information from the user regarding:
- **Overall Vision & Experience:** What is the desired look and feel (e.g., "modern and minimalist," "friendly and approachable," "data-intensive and professional")? What kind of experience should users have?
- **Key Interaction Paradigms:** Are there specific ways users will interact with core features (e.g., "drag-and-drop interface for X," "wizard-style setup for Y," "real-time dashboard for Z")?
- **Core Screens/Views (Conceptual):** From a product perspective, what are the most critical screens or views necessary to deliver the MVP's value? (e.g., "Login Screen," "Main Dashboard," "Item Detail Page," "Settings Page").
- **Accessibility Aspirations:** Any known high-level accessibility goals (e.g., "must be usable by screen reader users").
- **Branding Considerations (High-Level):** Any known branding elements or style guides that must be incorporated?
- **Target Devices/Platforms:** (e.g., "primarily web desktop," "mobile-first responsive web app").
This section is not intended to be a detailed UI specification but rather a product-focused brief to guide the subsequent detailed work by the Design Architect, who will create the comprehensive UI/UX Specification document.
}
## Technical Assumptions
This is where we can list information mostly to be used by the architect to produce the technical details. This could be anything we already know or found out from the user at a technical high level. Inquire about this from the user to get a basic idea of languages, frameworks, knowledge of starter templates, libraries, external apis, potential library choices etc...
- **Repository & Service Architecture:** {CRITICAL DECISION: Document the chosen repository structure (e.g., Monorepo, Polyrepo) and the high-level service architecture (e.g., Monolith, Microservices, Serverless functions within a Monorepo). Explain the rationale based on project goals, MVP scope, team structure, and scalability needs. This decision directly impacts the technical approach and informs the Architect Agent.}
### Testing requirements
How will we validate functionality beyond unit testing? Will we want manual scripts or testing, e2e, integration etc... figure this out from the user to populate this section
## Epic Overview
- **Epic {#}: {Title}**
- Goal: {A concise 1-2 sentence statement describing the primary objective and value of this Epic.}
- Story {#}: As a {type of user/system}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}.
- {Acceptance Criteria List}
- Story {#}: As a {type of user/system}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}.
- {Acceptance Criteria List}
- **Epic {#}: {Title}**
- Goal: {A concise 1-2 sentence statement describing the primary objective and value of this Epic.}
- Story {#}: As a {type of user/system}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}.
- {Acceptance Criteria List}
- Story {#}: As a {type of user/system}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}.
- {Acceptance Criteria List}
## Key Reference Documents
{ This section will be created later, from the sections prior to this being carved up into smaller documents }
## Out of Scope Ideas Post MVP
Anything you and the user agreed it out of scope or can be removed from scope to keep MVP lean. Consider the goals of the PRD and what might be extra gold plating or additional features that could wait until the MVP is completed and delivered to assess functionality and market fit or usage.
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ---------------------------- | -------------- |
----- END PRD START CHECKLIST OUTPUT ------
## Checklist Results Report
----- END Checklist START Architect Prompt ------
## Initial Architect Prompt
Based on our discussions and requirements analysis for the {Product Name}, I've compiled the following technical guidance to inform your architecture analysis and decisions to kick off Architecture Creation Mode:
### Technical Infrastructure
- **Repository & Service Architecture Decision:** {Reiterate the decision made in 'Technical Assumptions', e.g., Monorepo with Next.js frontend and Python FastAPI backend services within the same repo; or Polyrepo with separate Frontend (Next.js) and Backend (Spring Boot Microservices) repositories.}
- **Starter Project/Template:** {Information about any starter projects, templates, or existing codebases that should be used}
- **Hosting/Cloud Provider:** {Specified cloud platform (AWS, Azure, GCP, etc.) or hosting requirements}
- **Frontend Platform:** {Framework/library preferences or requirements (React, Angular, Vue, etc.)}
- **Backend Platform:** {Framework/language preferences or requirements (Node.js, Python/Django, etc.)}
- **Database Requirements:** {Relational, NoSQL, specific products or services preferred}
### Technical Constraints
- {List any technical constraints that impact architecture decisions}
- {Include any mandatory technologies, services, or platforms}
- {Note any integration requirements with specific technical implications}
### Deployment Considerations
- {Deployment frequency expectations}
- {CI/CD requirements}
- {Environment requirements (local, dev, staging, production)}
### Local Development & Testing Requirements
{Include this section only if the user has indicated these capabilities are important. If not applicable based on user preferences, you may remove this section.}
- {Requirements for local development environment}
- {Expectations for command-line testing capabilities}
- {Needs for testing across different environments}
- {Utility scripts or tools that should be provided}
- {Any specific testability requirements for components}
### Other Technical Considerations
- {Security requirements with technical implications}
- {Scalability needs with architectural impact}
- {Any other technical context the Architect should consider}
----- END PM Prompt -----

51
BETA-V3/templates/project-brief-tmpl.txt Normal file
View File

@@ -0,0 +1,51 @@
# Project Brief: {Project Name}
## Introduction / Problem Statement
{Describe the core idea, the problem being solved, or the opportunity being addressed. Why is this project needed?}
## Vision & Goals
- **Vision:** {Describe the high-level desired future state or impact of this project.}
- **Primary Goals:** {List 2-5 specific, measurable, achievable, relevant, time-bound (SMART) goals for the Minimum Viable Product (MVP).}
- Goal 1: ...
- Goal 2: ...
- **Success Metrics (Initial Ideas):** {How will we measure if the project/MVP is successful? List potential KPIs.}
## Target Audience / Users
{Describe the primary users of this product/system. Who are they? What are their key characteristics or needs relevant to this project?}
## Key Features / Scope (High-Level Ideas for MVP)
{List the core functionalities or features envisioned for the MVP. Keep this high-level; details will go in the PRD/Epics.}
- Feature Idea 1: ...
- Feature Idea 2: ...
- Feature Idea N: ...
## Post MVP Features / Scope and Ideas
{List the core functionalities or features envisioned as potential for POST MVP. Keep this high-level; details will go in the PRD/Epics/Architecture.}
- Feature Idea 1: ...
- Feature Idea 2: ...
- Feature Idea N: ...
## Known Technical Constraints or Preferences
- **Constraints:** {List any known limitations and technical mandates or preferences - e.g., budget, timeline, specific technology mandates, required integrations, compliance needs.}
- **Initial Architectural Preferences (if any):** {Capture any early thoughts or strong preferences regarding repository structure (e.g., monorepo, polyrepo) and overall service architecture (e.g., monolith, microservices, serverless components). This is not a final decision point but for initial awareness.}
- **Risks:** {Identify potential risks - e.g., technical challenges, resource availability, market acceptance, dependencies.}
- **User Preferences:** {Any specific requests from the user that are not a high level feature that could direct technology or library choices, or anything else that came up in the brainstorming or drafting of the PRD that is not included in prior document sections}
## Relevant Research (Optional)
{Link to or summarize findings from any initial research conducted (e.g., `deep-research-report-BA.md`).}
## PM Prompt
This Project Brief provides the full context for {Project Name}. Please start in 'PM MODE 1', review the brief thoroughly to work with the user to create the PRD section by section 1 at a time, asking for any necessary clarification or suggesting improvements as your mode 1 programming allows.
<example_handoff_prompt>
This Project Brief provides the full context for Mealmate. Please start in 'PM MODE 1', review the brief thoroughly to work with the user to create the PRD section by section 1 at a time, asking for any necessary clarification or suggesting improvements as your mode 1 programming allows.</example_handoff_prompt>

31
BETA-V3/templates/story-tmpl.txt Normal file
View File

@@ -0,0 +1,31 @@
# Story {EpicNum}.{StoryNum}: {Short Title Copied from Epic File}
## Status: { Draft | Approved | Done }
## Story
- As a [role]
- I want [action]
- so that [benefit]
## Acceptance Criteria (ACs)
{ Copy the Acceptance Criteria numbered list }
## Tasks / Subtasks
- [ ] Task 1 (AC: # if applicable)
- [ ] Subtask1.1...
- [ ] Task 2 (AC: # if applicable)
- [ ] Subtask 2.1...
- [ ] Task 3 (AC: # if applicable)
- [ ] Subtask 3.1...
## Story Progress Notes
### Agent Model Used: `<Agent Model Name/Version>`
### Completion Notes List
{Any notes about implementation choices, difficulties, or follow-up needed}
### Change Log