556 lines
25 KiB
Plaintext
556 lines
25 KiB
Plaintext
# Architecture Sub Document Templates
|
|
|
|
## Master Architecture Template
|
|
```Markdown
|
|
# {Project Name} Architecture Document
|
|
|
|
## Technical Summary
|
|
|
|
{Provide a brief (1-2 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). Explain the primary user interaction or data flow at a conceptual level.}
|
|
|
|
```mermaid
|
|
{Insert high-level system context or interaction diagram here - e.g., using Mermaid graph TD or C4 Model Context Diagram}
|
|
```
|
|
|
|
## Component View
|
|
|
|
{Describe the major logical components or services of the system and their responsibilities. Explain how they collaborate.}
|
|
|
|
```mermaid
|
|
{Insert component diagram here - e.g., using Mermaid graph TD or C4 Model Container/Component Diagram}
|
|
```
|
|
|
|
- Component A: {Description of responsibility}
|
|
- Component B: {Description of responsibility}
|
|
- {src/ Directory (if applicable): The application code in src/ is organized into logical modules... (briefly describe key subdirectories like clients, core, services, etc., referencing docs/project-structure.md for the full layout)}
|
|
|
|
## Key Architectural Decisions & Patterns
|
|
|
|
{List significant architectural choices and the patterns employed.}
|
|
|
|
- Pattern/Decision 1: {e.g., Choice of Database, Message Queue Usage, Authentication Strategy, API Design Style (REST/GraphQL)} - Justification: {...}
|
|
- Pattern/Decision 2: {...} - Justification: {...}
|
|
- (See docs/coding-standards.md for detailed coding patterns and error handling)
|
|
|
|
## Core Workflow / Sequence Diagrams (Optional)
|
|
|
|
{Illustrate key or complex workflows using sequence diagrams if helpful.}
|
|
|
|
## 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, Pulumi, ARM Templates} - 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}
|
|
- (See docs/environment-vars.md for configuration details)
|
|
|
|
## Key Reference Documents
|
|
|
|
{Link to other relevant documents in the docs/ folder.}
|
|
|
|
- docs/prd.md
|
|
- docs/epicN.md files
|
|
- docs/tech-stack.md
|
|
- docs/project-structure.md
|
|
- docs/coding-standards.md
|
|
- docs/api-reference.md
|
|
- docs/data-models.md
|
|
- docs/environment-vars.md
|
|
- docs/testing-strategy.md
|
|
- docs/ui-ux-spec.md (if applicable)
|
|
- ... (other relevant docs)
|
|
|
|
## Change Log
|
|
|
|
| Change | Date | Version | Description | Author |
|
|
| ------------- | ---------- | ------- | ---------------------------- | -------------- |
|
|
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft based on brief | {Agent/Person} |
|
|
| ... | ... | ... | ... | ... |
|
|
|
|
```
|
|
## Coding Standards Template
|
|
|
|
```Markdown
|
|
# {Project Name} Coding Standards and Patterns
|
|
|
|
## Architectural / Design Patterns Adopted
|
|
|
|
{List the key high-level patterns chosen in the architecture document.}
|
|
|
|
- **Pattern 1:** {e.g., Serverless, Event-Driven, Microservices, CQRS} - _Rationale/Reference:_ {Briefly why, or link to `docs/architecture.md` section}
|
|
- **Pattern 2:** {e.g., Dependency Injection, Repository Pattern, Module Pattern} - _Rationale/Reference:_ {...}
|
|
- **Pattern N:** {...}
|
|
|
|
## Coding Standards (Consider adding these to Dev Agent Context or Rules)
|
|
|
|
- **Primary Language(s):** {e.g., TypeScript 5.x, Python 3.11, Go 1.2x}
|
|
- **Primary Runtime(s):** {e.g., Node.js 22.x, Python Runtime for Lambda}
|
|
- **Style Guide & Linter:** {e.g., ESLint with Airbnb config, Prettier; Black, Flake8; Go fmt} - _Configuration:_ {Link to config files or describe setup}
|
|
- **Naming Conventions:**
|
|
- Variables: `{e.g., camelCase}`
|
|
- Functions: `{e.g., camelCase}`
|
|
- Classes/Types/Interfaces: `{e.g., PascalCase}`
|
|
- Constants: `{e.g., UPPER_SNAKE_CASE}`
|
|
- Files: `{e.g., kebab-case.ts, snake_case.py}`
|
|
- **File Structure:** Adhere to the layout defined in `docs/project-structure.md`.
|
|
- **Asynchronous Operations:** {e.g., Use `async`/`await` in TypeScript/Python, Goroutines/Channels in Go.}
|
|
- **Type Safety:** {e.g., Leverage TypeScript strict mode, Python type hints, Go static typing.} - _Type Definitions:_ {Location, e.g., `src/common/types.ts`}
|
|
- **Comments & Documentation:** {Expectations for code comments, docstrings, READMEs.}
|
|
- **Dependency Management:** {Tool used - e.g., npm, pip, Go modules. Policy on adding dependencies.}
|
|
|
|
## 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 `try/catch`, check response codes, implement retries with backoff for transient errors?}
|
|
- Input Validation: {Where and how is input validated?}
|
|
- Graceful Degradation vs. Critical Failure: {Define criteria for when to continue vs. halt.}
|
|
|
|
## Security Best Practices
|
|
|
|
{Outline key security considerations relevant to the codebase.}
|
|
|
|
- Input Sanitization/Validation: {...}
|
|
- Secrets Management: {How are secrets handled in code? Reference `docs/environment-vars.md` regarding storage.}
|
|
- Dependency Security: {Policy on checking for vulnerable dependencies.}
|
|
- Authentication/Authorization Checks: {Where should these be enforced?}
|
|
- {Other relevant practices...}
|
|
|
|
## Change Log
|
|
|
|
| Change | Date | Version | Description | Author |
|
|
| ------------- | ---------- | ------- | ------------- | -------------- |
|
|
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
|
|
| ... | ... | ... | ... | ... |
|
|
```
|
|
|
|
## Data Models Template
|
|
|
|
```Markdown
|
|
# {Project Name} Data Models
|
|
|
|
## 2. 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 specifically for data sent to or received from APIs, if they differ significantly from the core entities. Reference `docs/api-reference.md`.}
|
|
|
|
### {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"]
|
|
}
|
|
```
|
|
|
|
## Change Log
|
|
|
|
| Change | Date | Version | Description | Author |
|
|
| ------------- | ---------- | ------- | ------------- | -------------- |
|
|
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
|
|
| ... | ... | ... | ... | ... |
|
|
```
|
|
|
|
## Environment Vars Templates
|
|
|
|
```Markdown
|
|
# {Project Name} Environment Variables
|
|
|
|
## Configuration Loading Mechanism
|
|
|
|
{Describe how environment variables are loaded into the application.}
|
|
|
|
- **Local Development:** {e.g., Using `.env` file with `dotenv` library.}
|
|
- **Deployment (e.g., AWS Lambda, Kubernetes):** {e.g., Set via Lambda function configuration, Kubernetes Secrets/ConfigMaps.}
|
|
|
|
## Required Variables
|
|
|
|
{List all environment variables used by the application.}
|
|
|
|
| Variable Name | Description | Example / Default Value | Required? (Yes/No) | Sensitive? (Yes/No) |
|
|
| :------------------- | :---------------------------------------------- | :------------------------------------ | :----------------- | :------------------ |
|
|
| `NODE_ENV` | Runtime environment | `development` / `production` | Yes | No |
|
|
| `PORT` | Port the application listens on (if applicable) | `8080` | No | No |
|
|
| `DATABASE_URL` | Connection string for the primary database | `postgresql://user:pass@host:port/db` | Yes | Yes |
|
|
| `EXTERNAL_API_KEY` | API Key for {External Service Name} | `sk_...` | Yes | Yes |
|
|
| `S3_BUCKET_NAME` | Name of the S3 bucket for {Purpose} | `my-app-data-bucket-...` | Yes | No |
|
|
| `FEATURE_FLAG_X` | Enables/disables experimental feature X | `false` | No | No |
|
|
| `{ANOTHER_VARIABLE}` | {Description} | {Example} | {Yes/No} | {Yes/No} |
|
|
| ... | ... | ... | ... | ... |
|
|
|
|
## Notes
|
|
|
|
- **Secrets Management:** {Explain how sensitive variables (API Keys, passwords) should be handled, especially in production (e.g., "Use AWS Secrets Manager", "Inject via CI/CD pipeline").}
|
|
- **`.env.example`:** {Mention that an `.env.example` file should be maintained in the repository with placeholder values for developers.}
|
|
- **Validation:** {Is there code that validates the presence or format of these variables at startup?}
|
|
|
|
## Change Log
|
|
|
|
| Change | Date | Version | Description | Author |
|
|
| ------------- | ---------- | ------- | ------------- | -------------- |
|
|
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
|
|
| ... | ... | ... | ... | ... |
|
|
|
|
```
|
|
|
|
## Project Structure Template Example
|
|
|
|
```Markdown
|
|
# {Project Name} Project Structure
|
|
|
|
{Provide an ASCII or Mermaid diagram representing the project's folder structure such as the following example.}
|
|
|
|
```plaintext
|
|
{project-root}/
|
|
├── .github/ # CI/CD workflows (e.g., GitHub Actions)
|
|
│ └── workflows/
|
|
│ └── main.yml
|
|
├── .vscode/ # VSCode settings (optional)
|
|
│ └── settings.json
|
|
├── build/ # Compiled output (if applicable, often git-ignored)
|
|
├── config/ # Static configuration files (if any)
|
|
├── docs/ # Project documentation (PRD, Arch, etc.)
|
|
│ ├── index.md
|
|
│ └── ... (other .md files)
|
|
├── infra/ # Infrastructure as Code (e.g., CDK, Terraform)
|
|
│ └── lib/
|
|
│ └── bin/
|
|
├── node_modules/ # Project dependencies (git-ignored)
|
|
├── scripts/ # Utility scripts (build, deploy helpers, etc.)
|
|
├── src/ # Application source code
|
|
│ ├── common/ # Shared utilities, types, constants
|
|
│ ├── components/ # Reusable UI components (if UI exists)
|
|
│ ├── features/ # Feature-specific modules (alternative structure)
|
|
│ │ └── feature-a/
|
|
│ ├── core/ # Core business logic
|
|
│ ├── clients/ # External API/Service clients
|
|
│ ├── services/ # Internal services / Cloud SDK wrappers
|
|
│ ├── pages/ / routes/ # UI pages or API route definitions
|
|
│ └── main.ts / index.ts / app.ts # Application entry point
|
|
├── stories/ # Generated story files for development (optional)
|
|
│ └── epic1/
|
|
├── test/ # Automated tests
|
|
│ ├── unit/ # Unit tests (mirroring src structure)
|
|
│ ├── integration/ # Integration tests
|
|
│ └── e2e/ # End-to-end tests
|
|
├── .env.example # Example environment variables
|
|
├── .gitignore # Git ignore rules
|
|
├── package.json # Project manifest and dependencies
|
|
├── tsconfig.json # TypeScript configuration (if applicable)
|
|
├── Dockerfile # Docker build instructions (if applicable)
|
|
└── README.md # Project overview and setup instructions
|
|
```
|
|
|
|
(Adjust the example tree based on the actual project type - e.g., Python would have requirements.txt, etc.)
|
|
|
|
## Key Directory Descriptions
|
|
|
|
docs/: Contains all project planning and reference documentation.
|
|
infra/: Holds the Infrastructure as Code definitions (e.g., AWS CDK, Terraform).
|
|
src/: Contains the main application source code.
|
|
common/: Code shared across multiple modules (utilities, types, constants). Avoid business logic here.
|
|
core/ / domain/: Core business logic, entities, use cases, independent of frameworks/external services.
|
|
clients/: Modules responsible for communicating with external APIs or services.
|
|
services/ / adapters/ / infrastructure/: Implementation details, interactions with databases, cloud SDKs, frameworks.
|
|
routes/ / controllers/ / pages/: Entry points for API requests or UI views.
|
|
test/: Contains all automated tests, mirroring the src/ structure where applicable.
|
|
scripts/: Helper scripts for build, deployment, database migrations, etc.
|
|
|
|
## Notes
|
|
|
|
{Mention any specific build output paths, compiler configuration pointers, or other relevant structural notes.}
|
|
|
|
## Change Log
|
|
|
|
| Change | Date | Version | Description | Author |
|
|
| ------------- | ---------- | ------- | ------------- | -------------- |
|
|
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
|
|
| ... | ... | ... | ... | ... |
|
|
```
|
|
|
|
## Tech Stack Template
|
|
|
|
```Markdown
|
|
# {Project Name} Technology Stack
|
|
|
|
## Technology Choices
|
|
|
|
| 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} | {...} |
|
|
|
|
## Change Log
|
|
|
|
| Change | Date | Version | Description | Author |
|
|
| ------------- | ---------- | ------- | ------------- | -------------- |
|
|
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
|
|
| ... | ... | ... | ... |
|
|
|
|
```
|
|
|
|
## Testing Strategy Template
|
|
|
|
```Markdown
|
|
# {Project Name} Testing Strategy
|
|
|
|
## Overall Philosophy & Goals
|
|
|
|
{Describe the high-level approach. e.g., "Follow the Testing Pyramid/Trophy principle.", "Automate extensively.", "Focus on testing business logic and key integrations.", "Ensure tests run efficiently in CI/CD."}
|
|
|
|
- Goal 1: {e.g., Achieve X% code coverage for critical modules.}
|
|
- Goal 2: {e.g., Prevent regressions in core functionality.}
|
|
- Goal 3: {e.g., Enable confident refactoring.}
|
|
|
|
## Testing Levels
|
|
|
|
### Unit Tests
|
|
|
|
- **Scope:** Test individual functions, methods, or components in isolation. Focus on business logic, calculations, and conditional paths within a single module.
|
|
- **Tools:** {e.g., Jest, Pytest, Go testing package, JUnit, NUnit}
|
|
- **Mocking/Stubbing:** {How are dependencies mocked? e.g., Jest mocks, Mockito, Go interfaces}
|
|
- **Location:** {e.g., `test/unit/`, alongside source files (`*.test.ts`)}
|
|
- **Expectations:** {e.g., Should cover all significant logic paths. Fast execution.}
|
|
|
|
### Integration Tests
|
|
|
|
- **Scope:** Verify the interaction and collaboration between multiple internal components or modules. Test the flow of data and control within a specific feature or workflow slice. May involve mocking external APIs or databases, or using test containers.
|
|
- **Tools:** {e.g., Jest, Pytest, Go testing package, Testcontainers, Supertest (for APIs)}
|
|
- **Location:** {e.g., `test/integration/`}
|
|
- **Expectations:** {e.g., Focus on module boundaries and contracts. Slower than unit tests.}
|
|
|
|
### End-to-End (E2E) / Acceptance Tests
|
|
|
|
- **Scope:** Test the entire system flow from an end-user perspective. Interact with the application through its external interfaces (UI or API). Validate complete user journeys or business processes against real or near-real dependencies.
|
|
- **Tools:** {e.g., Playwright, Cypress, Selenium (for UI); Postman/Newman, K6 (for API)}
|
|
- **Environment:** {Run against deployed environments (e.g., Staging) or a locally composed setup (Docker Compose).}
|
|
- **Location:** {e.g., `test/e2e/`}
|
|
- **Expectations:** {Cover critical user paths. Slower, potentially flaky, run less frequently (e.g., pre-release, nightly).}
|
|
|
|
### Manual / Exploratory Testing (Optional)
|
|
|
|
- **Scope:** {Where is manual testing still required? e.g., Exploratory testing for usability, testing complex edge cases.}
|
|
- **Process:** {How is it performed and tracked?}
|
|
|
|
## Specialized Testing Types (Add sections as needed)
|
|
|
|
### Performance Testing
|
|
|
|
- **Scope & Goals:** {What needs performance testing? What are the targets (latency, throughput)?}
|
|
- **Tools:** {e.g., K6, JMeter, Locust}
|
|
|
|
### Security Testing
|
|
|
|
- **Scope & Goals:** {e.g., Dependency scanning, SAST, DAST, penetration testing requirements.}
|
|
- **Tools:** {e.g., Snyk, OWASP ZAP, Dependabot}
|
|
|
|
### Accessibility Testing (UI)
|
|
|
|
- **Scope & Goals:** {Target WCAG level, key areas.}
|
|
- **Tools:** {e.g., Axe, Lighthouse, manual checks}
|
|
|
|
### Visual Regression Testing (UI)
|
|
|
|
- **Scope & Goals:** {Prevent unintended visual changes.}
|
|
- **Tools:** {e.g., Percy, Applitools Eyes, Playwright visual comparisons}
|
|
|
|
## Test Data Management
|
|
|
|
{How is test data generated, managed, and reset for different testing levels?}
|
|
|
|
## CI/CD Integration
|
|
|
|
{How and when are tests executed in the CI/CD pipeline? What constitutes a pipeline failure?}
|
|
|
|
## Change Log
|
|
|
|
| Change | Date | Version | Description | Author |
|
|
| ------------- | ---------- | ------- | ------------- | -------------- |
|
|
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
|
|
| ... | ... | ... | ... | ... |
|
|
|
|
```
|
|
|
|
## API Reference Template
|
|
|
|
```Markdown
|
|
# {Project Name} 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 or link to `docs/data-models.md`}
|
|
- Example Request: `{Code block}`
|
|
- Success Response Schema (Code: `200 OK`): {JSON schema or link}
|
|
- Error Response Schema(s) (Codes: `4xx`, `5xx`): {JSON schema or link}
|
|
- 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: {...}
|
|
- Success Response Schema (Code: `200 OK`): {...}
|
|
- Error Response Schema(s) (Codes: `4xx`, `5xx`): {...}
|
|
- **`{HTTP Method} {/another/endpoint}`:** {...}
|
|
|
|
## AWS Service SDK Usage (or other Cloud Providers)
|
|
|
|
{Detail interactions with cloud provider services via SDKs.}
|
|
|
|
### {AWS Service Name, e.g., S3}
|
|
|
|
- **Purpose:** {Why is this service used?}
|
|
- **SDK Package:** {e.g., `@aws-sdk/client-s3`}
|
|
- **Key Operations Used:** {e.g., `GetObjectCommand`, `PutObjectCommand`}
|
|
- Operation 1: {Brief description of usage context}
|
|
- Operation 2: {...}
|
|
- **Key Resource Identifiers:** {e.g., Bucket names, Table names - reference `docs/environment-vars.md`}
|
|
|
|
### {Another AWS Service Name, e.g., SES}
|
|
|
|
{...}
|
|
|
|
## 5. Change Log
|
|
|
|
| Change | Date | Version | Description | Author |
|
|
| ------------- | ---------- | ------- | ------------- | -------------- |
|
|
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
|
|
| ... | ... | ... | ... | ... |
|
|
```
|