aiox-core 5.0.7 → 5.0.8

package/.claude/skills/architect-first/assets/architecture-template.md

@@ -0,0 +1,505 @@
+# [System/Feature Name] Architecture
+
+**Version:** 1.0
+**Date:** YYYY-MM-DD
+**Author:** [Your Name]
+**Status:** [Draft | Review | Approved | Implemented]
+
+---
+
+## Overview
+
+### Purpose
+[2-3 sentences describing what this system/feature does and why it exists]
+
+### Scope
+**In Scope:**
+- [Feature/capability 1]
+- [Feature/capability 2]
+- [Feature/capability 3]
+
+**Out of Scope:**
+- [What this will NOT do]
+- [Future enhancements not in current scope]
+
+### Success Criteria
+- [ ] [Measurable criterion 1]
+- [ ] [Measurable criterion 2]
+- [ ] [Measurable criterion 3]
+
+---
+
+## Context
+
+### Problem Statement
+[Describe the problem this architecture solves]
+
+### Current State
+[Describe existing systems/architecture if applicable]
+
+### Goals
+1. [Primary goal]
+2. [Secondary goal]
+3. [Additional goal]
+
+### Constraints
+- **Technical:** [Technical limitations or requirements]
+- **Business:** [Budget, timeline, resource constraints]
+- **Regulatory:** [Compliance requirements if applicable]
+
+---
+
+## Architecture Design
+
+### System Architecture Diagram
+
+```
+[Include diagram here - can be ASCII, Mermaid, or link to image]
+
+Example:
+┌─────────────┐      ┌─────────────┐      ┌─────────────┐
+│   Client    │─────>│   Server    │─────>│  Database   │
+└─────────────┘      └─────────────┘      └─────────────┘
+```
+
+### Component Architecture
+
+#### Component 1: [Name]
+- **Purpose:** [What this component does]
+- **Responsibilities:**
+  - [Responsibility 1]
+  - [Responsibility 2]
+- **Interfaces:**
+  - Input: [What it receives]
+  - Output: [What it provides]
+- **Dependencies:** [What it depends on]
+
+#### Component 2: [Name]
+- **Purpose:** [What this component does]
+- **Responsibilities:**
+  - [Responsibility 1]
+  - [Responsibility 2]
+- **Interfaces:**
+  - Input: [What it receives]
+  - Output: [What it provides]
+- **Dependencies:** [What it depends on]
+
+[Add more components as needed]
+
+---
+
+## Data Flow
+
+### Primary Workflow
+
+```
+1. [Step 1] → [Component A]
+2. [Step 2] → [Component B]
+3. [Step 3] → [Component C]
+4. [Result/Output]
+```
+
+### Data Flow Diagram
+
+```
+[Include data flow diagram]
+
+Example:
+User Input → Validation → Processing → Storage → Response
+```
+
+### Data Models
+
+#### Entity: [Name]
+```yaml
+entity_name:
+  field1: type  # description
+  field2: type  # description
+  field3: type  # description
+```
+
+#### Entity: [Name]
+```yaml
+entity_name:
+  field1: type  # description
+  field2: type  # description
+```
+
+---
+
+## Integration Points
+
+### External Systems
+
+#### Integration 1: [System Name]
+- **Purpose:** [Why we integrate]
+- **Type:** [API, Database, Message Queue, etc.]
+- **Protocol:** [REST, GraphQL, gRPC, etc.]
+- **Authentication:** [OAuth, API Key, etc.]
+- **Endpoints:**
+  - `GET /endpoint1` - [Description]
+  - `POST /endpoint2` - [Description]
+- **Error Handling:** [How errors are handled]
+
+#### Integration 2: [System Name]
+[Same structure as above]
+
+### Internal APIs
+
+#### API 1: [Name]
+- **Base URL:** `/api/v1/resource`
+- **Endpoints:**
+  - `GET /resource` - List resources
+  - `POST /resource` - Create resource
+  - `PUT /resource/:id` - Update resource
+  - `DELETE /resource/:id` - Delete resource
+- **Authentication:** [Required auth method]
+- **Rate Limiting:** [Limits if applicable]
+
+---
+
+## Configuration
+
+### Configuration Schema
+
+```yaml
+# config.yaml
+system:
+  name: string              # System name
+  environment: string       # dev|staging|production
+  log_level: string        # debug|info|warning|error
+
+database:
+  host: string             # Database host
+  port: integer            # Database port
+  name: string             # Database name
+  pool_size: integer       # Connection pool size
+
+integrations:
+  service_a:
+    enabled: boolean       # Enable/disable integration
+    endpoint: string       # Service endpoint URL
+    api_key: string       # API key (from secrets)
+    timeout: integer      # Request timeout in seconds
+
+features:
+  feature_x:
+    enabled: boolean       # Feature flag
+    settings:
+      param1: value       # Feature-specific parameter
+      param2: value
+```
+
+### Environment Variables
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `ENV` | Environment (dev/staging/prod) | Yes | dev |
+| `DB_HOST` | Database hostname | Yes | - |
+| `API_KEY` | External API key | Yes | - |
+| `LOG_LEVEL` | Logging level | No | info |
+
+### Configuration Override
+
+Configuration priority (highest to lowest):
+1. Environment variables
+2. Command-line arguments
+3. Configuration file (`config.yaml`)
+4. Default values
+
+---
+
+## Deployment
+
+### Architecture Tiers
+
+- **Presentation:** [Frontend/UI components]
+- **Application:** [Business logic/API layer]
+- **Data:** [Database/storage layer]
+
+### Deployment Diagram
+
+```
+[Include deployment architecture]
+
+Example:
+┌─────────────────┐
+│   Load Balancer │
+└────────┬────────┘
+         │
+    ┌────┴────┐
+    │         │
+┌───▼──┐  ┌──▼───┐
+│ App1 │  │ App2 │
+└───┬──┘  └──┬───┘
+    │         │
+    └────┬────┘
+         │
+    ┌────▼────┐
+    │   DB    │
+    └─────────┘
+```
+
+### Infrastructure Requirements
+
+- **Compute:** [CPU/memory requirements]
+- **Storage:** [Disk space requirements]
+- **Network:** [Bandwidth/latency requirements]
+- **Scaling:** [Horizontal/vertical scaling approach]
+
+---
+
+## Security
+
+### Authentication & Authorization
+- **User Auth:** [Method used - OAuth, JWT, etc.]
+- **Service Auth:** [API keys, mutual TLS, etc.]
+- **Roles:** [User roles and permissions]
+
+### Data Security
+- **Encryption at Rest:** [How data is encrypted when stored]
+- **Encryption in Transit:** [TLS/SSL configuration]
+- **Secrets Management:** [How secrets are stored/accessed]
+
+### Security Boundaries
+- [Boundary 1 and its protection mechanism]
+- [Boundary 2 and its protection mechanism]
+
+---
+
+## Performance
+
+### Performance Requirements
+- **Response Time:** [Target response times]
+- **Throughput:** [Requests per second]
+- **Concurrency:** [Concurrent users/requests]
+
+### Scalability Strategy
+- **Horizontal Scaling:** [How to scale out]
+- **Vertical Scaling:** [How to scale up]
+- **Caching:** [Caching strategy]
+- **Database:** [DB scaling approach]
+
+### Performance Optimizations
+- [Optimization 1]
+- [Optimization 2]
+- [Optimization 3]
+
+---
+
+## Monitoring & Observability
+
+### Metrics
+- **System Metrics:**
+  - CPU usage
+  - Memory usage
+  - Disk I/O
+  - Network I/O
+
+- **Application Metrics:**
+  - Request rate
+  - Error rate
+  - Response time (p50, p95, p99)
+  - Active connections
+
+- **Business Metrics:**
+  - [Business-specific metric 1]
+  - [Business-specific metric 2]
+
+### Logging
+- **Log Levels:** DEBUG, INFO, WARNING, ERROR, CRITICAL
+- **Log Format:** JSON structured logs
+- **Log Aggregation:** [Tool/service used]
+- **Retention:** [Log retention policy]
+
+### Alerting
+- **Critical Alerts:**
+  - [Alert 1 and threshold]
+  - [Alert 2 and threshold]
+
+- **Warning Alerts:**
+  - [Alert 1 and threshold]
+  - [Alert 2 and threshold]
+
+### Tracing
+- **Distributed Tracing:** [Tool used - Jaeger, Zipkin, etc.]
+- **Trace Sampling:** [Sampling strategy]
+
+---
+
+## Testing Strategy
+
+### Unit Testing
+- **Coverage Target:** 80% minimum
+- **Framework:** [Test framework used]
+- **Key Areas:**
+  - Business logic
+  - Data transformations
+  - Utility functions
+
+### Integration Testing
+- **Scope:** Component interactions
+- **Framework:** [Test framework used]
+- **Key Scenarios:**
+  - [Scenario 1]
+  - [Scenario 2]
+
+### End-to-End Testing
+- **Scope:** Complete user workflows
+- **Framework:** [Test framework used]
+- **Key Workflows:**
+  - [Workflow 1]
+  - [Workflow 2]
+
+### Performance Testing
+- **Load Testing:** [Tool and targets]
+- **Stress Testing:** [Limits to test]
+- **Benchmarks:** [Performance benchmarks]
+
+---
+
+## Architectural Decisions
+
+### Decision 1: [Decision Title]
+
+**Context:**
+[What situation led to this decision?]
+
+**Options Considered:**
+
+**Option A: [Name]**
+- Pros: [Benefits]
+- Cons: [Drawbacks]
+
+**Option B: [Name]**
+- Pros: [Benefits]
+- Cons: [Drawbacks]
+
+**Option C: [Name]**
+- Pros: [Benefits]
+- Cons: [Drawbacks]
+
+**Decision:**
+Chose Option [X] because [rationale]
+
+**Consequences:**
+- [Positive consequence 1]
+- [Positive consequence 2]
+- [Trade-off/negative consequence]
+
+**Validation:**
+- [ ] Product Owner approved
+- [ ] Architect approved
+- [ ] Technical lead approved
+
+---
+
+### Decision 2: [Decision Title]
+[Same structure as Decision 1]
+
+---
+
+## Risks & Mitigation
+
+| Risk | Severity | Impact | Mitigation Strategy | Owner |
+|------|----------|--------|-------------------|-------|
+| [Risk 1] | High/Med/Low | [Impact description] | [How to mitigate] | [Name] |
+| [Risk 2] | High/Med/Low | [Impact description] | [How to mitigate] | [Name] |
+| [Risk 3] | High/Med/Low | [Impact description] | [How to mitigate] | [Name] |
+
+---
+
+## Dependencies
+
+### External Dependencies
+- **Library/Service 1:** [Purpose, version, license]
+- **Library/Service 2:** [Purpose, version, license]
+
+### Internal Dependencies
+- **Module 1:** [What it provides, version]
+- **Module 2:** [What it provides, version]
+
+### Dependency Graph
+```
+[Visual representation of dependency relationships]
+```
+
+---
+
+## Migration & Rollout
+
+### Migration Strategy
+[How to migrate from current state to new architecture]
+
+1. **Phase 1:** [Description]
+   - Timeline: [Duration]
+   - Deliverables: [What gets delivered]
+
+2. **Phase 2:** [Description]
+   - Timeline: [Duration]
+   - Deliverables: [What gets delivered]
+
+3. **Phase 3:** [Description]
+   - Timeline: [Duration]
+   - Deliverables: [What gets delivered]
+
+### Rollback Plan
+[How to rollback if issues arise]
+
+1. [Rollback step 1]
+2. [Rollback step 2]
+3. [Rollback step 3]
+
+---
+
+## Open Questions
+
+- [ ] [Question 1 that needs resolution]
+- [ ] [Question 2 that needs resolution]
+- [ ] [Question 3 that needs resolution]
+
+---
+
+## Approvals
+
+| Role | Name | Signature | Date |
+|------|------|-----------|------|
+| Product Owner | | | |
+| Architect | | | |
+| Tech Lead | | | |
+| Security | | | |
+
+---
+
+## References
+
+- [Link to related design doc]
+- [Link to API documentation]
+- [Link to external resource]
+
+---
+
+## Appendix
+
+### Glossary
+- **Term 1:** Definition
+- **Term 2:** Definition
+
+### Additional Diagrams
+[Any supplementary diagrams]
+
+### Code Examples
+```python
+# Example implementation snippet
+def example_function():
+    """Demonstrates key architectural pattern"""
+    pass
+```
+
+---
+
+**Document History**
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | YYYY-MM-DD | [Name] | Initial version |