trinity-method-sdk 2.0.0

package/dist/templates/knowledge-base/ARCHITECTURE.md.template

@@ -0,0 +1,452 @@
+# {{PROJECT_NAME}} Architecture
+**Trinity Method v2.0**
+**Technology Stack**: {{TECHNOLOGY_STACK}}
+**Framework**: {{PRIMARY_FRAMEWORK}}
+**Last Updated**: {{CURRENT_DATE}}
+
+---
+
+## SYSTEM OVERVIEW
+
+### Technology Profile
+```{{LANGUAGE}}
+const {{PROJECT_VAR_NAME}}Stack = {
+  framework: '{{PRIMARY_FRAMEWORK}}',
+  language: '{{LANGUAGE}}',
+  backend: '{{BACKEND_FRAMEWORK}}',
+  database: '{{DATABASE_TYPE}}',
+  authentication: '{{AUTH_TYPE}}',
+  styling: '{{STYLING_SOLUTION}}',
+  testing: '{{TESTING_FRAMEWORK}}',
+  buildTool: '{{BUILD_TOOL}}',
+  deployment: '{{DEPLOYMENT_PLATFORM}}'
+};
+```
+
+### Repository Structure
+```
+{{PROJECT_NAME}}/
+├── {{SOURCE_DIR}}/              # Main source code
+├── trinity/                     # Trinity Method implementation
+│   ├── knowledge-base/         # Architecture & documentation
+├── tests/                      # Test suites
+└── docs/                       # Additional documentation
+```
+
+---
+
+## COMPONENT ARCHITECTURE
+
+### Core Components
+| Component | Responsibility | Dependencies | Status |
+|-----------|---------------|--------------|---------|
+| {{COMPONENT_1}} | {{RESPONSIBILITY_1}} | {{DEPS_1}} | {{STATUS_1}} |
+| {{COMPONENT_2}} | {{RESPONSIBILITY_2}} | {{DEPS_2}} | {{STATUS_2}} |
+| {{COMPONENT_3}} | {{RESPONSIBILITY_3}} | {{DEPS_3}} | {{STATUS_3}} |
+
+### {{FRAMEWORK}}-Specific Architecture
+- **Component Pattern**: {{COMPONENT_PATTERN}}
+- **State Management**: {{STATE_MANAGEMENT}}
+- **Routing Strategy**: {{ROUTING_STRATEGY}}
+- **Data Flow Pattern**: {{DATA_FLOW_PATTERN}}
+
+### Integration Points
+```yaml
+Internal_Integrations:
+  - Component: {{INTERNAL_1}}
+    Protocol: {{PROTOCOL_1}}
+    Data_Format: {{FORMAT_1}}
+
+External_Integrations:
+  - Service: {{EXTERNAL_1}}
+    API_Type: {{API_TYPE_1}}
+    Authentication: {{AUTH_METHOD_1}}
+```
+
+---
+
+## DATA ARCHITECTURE
+
+### Data Models
+```{{LANGUAGE}}
+// Core data structures
+{{DATA_MODEL_EXAMPLE}}
+```
+
+### Database Schema
+- **Primary Database**: {{DATABASE_TYPE}}
+- **Schema Version**: {{SCHEMA_VERSION}}
+- **Migration Strategy**: {{MIGRATION_STRATEGY}}
+
+### Data Flow
+1. **Input Layer**: {{INPUT_DESCRIPTION}}
+2. **Processing Layer**: {{PROCESSING_DESCRIPTION}}
+3. **Storage Layer**: {{STORAGE_DESCRIPTION}}
+4. **Output Layer**: {{OUTPUT_DESCRIPTION}}
+
+---
+
+## API ARCHITECTURE
+
+### API Design Pattern
+- **Pattern**: {{API_PATTERN}} (REST/GraphQL/RPC)
+- **Version**: {{API_VERSION}}
+- **Documentation**: {{API_DOCS_LOCATION}}
+
+### Endpoint Structure
+```
+{{API_BASE_URL}}/
+├── /auth/              # Authentication endpoints
+├── /api/v1/           # Main API endpoints
+├── /admin/            # Administrative endpoints
+└── /health/           # Health check endpoints
+```
+
+### Authentication & Authorization
+- **Auth Method**: {{AUTH_METHOD}}
+- **Token Type**: {{TOKEN_TYPE}}
+- **Session Management**: {{SESSION_MANAGEMENT}}
+- **Permission Model**: {{PERMISSION_MODEL}}
+
+---
+
+## PERFORMANCE ARCHITECTURE
+
+### Performance Baselines
+```yaml
+Performance_Targets:
+  Initial_Load: <{{LOAD_TIME_TARGET}}ms
+  API_Response: <{{API_RESPONSE_TARGET}}ms
+  Database_Query: <{{DB_QUERY_TARGET}}ms
+  Memory_Usage: <{{MEMORY_TARGET}}MB
+  CPU_Usage: <{{CPU_TARGET}}%
+```
+
+### Optimization Strategies
+1. **Caching**: {{CACHING_STRATEGY}}
+2. **Bundle Optimization**: {{BUNDLE_STRATEGY}}
+3. **Lazy Loading**: {{LAZY_LOADING_STRATEGY}}
+4. **Database Indexing**: {{INDEXING_STRATEGY}}
+
+### Monitoring Points
+- Application Performance Monitoring (APM)
+- Error tracking and alerting
+- Performance metrics dashboard
+- User experience metrics
+
+---
+
+## SECURITY ARCHITECTURE
+
+### Security Layers
+1. **Network Security**: {{NETWORK_SECURITY}}
+2. **Application Security**: {{APP_SECURITY}}
+3. **Data Security**: {{DATA_SECURITY}}
+4. **Infrastructure Security**: {{INFRA_SECURITY}}
+
+### Security Measures
+```yaml
+Input_Validation:
+  - Type: {{VALIDATION_TYPE}}
+  - Library: {{VALIDATION_LIBRARY}}
+
+Encryption:
+  - At_Rest: {{ENCRYPTION_AT_REST}}
+  - In_Transit: {{ENCRYPTION_IN_TRANSIT}}
+
+Access_Control:
+  - Method: {{ACCESS_CONTROL_METHOD}}
+  - Granularity: {{ACCESS_GRANULARITY}}
+```
+
+---
+
+## DEPLOYMENT ARCHITECTURE
+
+### Deployment Environment
+- **Development**: {{DEV_ENVIRONMENT}}
+- **Staging**: {{STAGING_ENVIRONMENT}}
+- **Production**: {{PROD_ENVIRONMENT}}
+
+### CI/CD Pipeline
+```yaml
+Pipeline_Stages:
+  1_Build:
+    - Compile code
+    - Run linters
+    - Generate assets
+
+  2_Test:
+    - Unit tests
+    - Integration tests
+    - E2E tests
+
+  3_Deploy:
+    - Environment validation
+    - Deployment execution
+    - Health checks
+```
+
+### Infrastructure
+- **Hosting**: {{HOSTING_PROVIDER}}
+- **Container**: {{CONTAINER_TECH}}
+- **Orchestration**: {{ORCHESTRATION}}
+- **Monitoring**: {{MONITORING_TOOLS}}
+
+---
+
+## SCALABILITY ARCHITECTURE
+
+### Current Capacity
+- **Users**: {{CURRENT_USER_CAPACITY}}
+- **Requests/sec**: {{CURRENT_RPS}}
+- **Data Volume**: {{CURRENT_DATA_VOLUME}}
+
+### Scaling Strategy
+1. **Horizontal Scaling**: {{H_SCALING_STRATEGY}}
+2. **Vertical Scaling**: {{V_SCALING_STRATEGY}}
+3. **Database Scaling**: {{DB_SCALING_STRATEGY}}
+4. **Caching Layer**: {{CACHE_SCALING_STRATEGY}}
+
+### Bottleneck Analysis
+| Component | Current Limit | Scaling Solution | Priority |
+|-----------|--------------|------------------|----------|
+| {{BOTTLENECK_1}} | {{LIMIT_1}} | {{SOLUTION_1}} | {{PRIORITY_1}} |
+| {{BOTTLENECK_2}} | {{LIMIT_2}} | {{SOLUTION_2}} | {{PRIORITY_2}} |
+
+---
+
+## TESTING ARCHITECTURE
+
+### Test Strategy
+```yaml
+Test_Coverage_Targets:
+  Unit_Tests: >{{UNIT_COVERAGE}}%
+  Integration_Tests: >{{INTEGRATION_COVERAGE}}%
+  E2E_Tests: Critical paths
+
+Test_Execution:
+  Pre_Commit: Unit tests
+  Pre_Merge: All tests
+  Nightly: Full regression
+```
+
+### Testing Framework
+- **Unit Testing**: {{UNIT_TEST_FRAMEWORK}}
+- **Integration Testing**: {{INTEGRATION_TEST_FRAMEWORK}}
+- **E2E Testing**: {{E2E_TEST_FRAMEWORK}}
+- **Performance Testing**: {{PERF_TEST_FRAMEWORK}}
+
+---
+
+## MAINTENANCE ARCHITECTURE
+
+### Logging Strategy
+- **Log Levels**: {{LOG_LEVELS}}
+- **Log Aggregation**: {{LOG_AGGREGATION}}
+- **Log Retention**: {{LOG_RETENTION}}
+
+### Error Handling
+```{{LANGUAGE}}
+// Error handling pattern
+{{ERROR_HANDLING_PATTERN}}
+```
+
+### Debugging Architecture
+- **Debug Points**: Entry/Exit logging in all functions
+- **Debug Tools**: {{DEBUG_TOOLS}}
+- **Profiling Tools**: {{PROFILING_TOOLS}}
+
+---
+
+## TECHNICAL DECISIONS LOG
+
+### Key Decisions Made
+1. **{{DECISION_1}}**: {{RATIONALE_1}}
+2. **{{DECISION_2}}**: {{RATIONALE_2}}
+3. **{{DECISION_3}}**: {{RATIONALE_3}}
+
+### Technology Constraints
+- {{CONSTRAINT_1}}
+- {{CONSTRAINT_2}}
+- {{CONSTRAINT_3}}
+
+---
+
+## ARCHITECTURE EVOLUTION
+
+### Planned Improvements
+1. **Short-term** (Next Sprint):
+   - {{SHORT_TERM_1}}
+   - {{SHORT_TERM_2}}
+
+2. **Medium-term** (Next Quarter):
+   - {{MEDIUM_TERM_1}}
+   - {{MEDIUM_TERM_2}}
+
+3. **Long-term** (Next Year):
+   - {{LONG_TERM_1}}
+   - {{LONG_TERM_2}}
+
+### Migration Path
+```mermaid
+graph LR
+    A[Current State] --> B[Phase 1]
+    B --> C[Phase 2]
+    C --> D[Target State]
+```
+
+---
+
+## TRINITY METHOD INTEGRATION
+
+### Investigation Points
+- Component boundaries for investigation
+- Data flow checkpoints
+- Integration test points
+- Performance monitoring locations
+
+### Knowledge Capture
+- Architecture decisions recorded here
+- Patterns documented in trinity/patterns/
+- Issues tracked in trinity/knowledge-base/ISSUES.md
+- Sessions archived in trinity/sessions/
+
+---
+
+## 📝 WHEN TO UPDATE THIS DOCUMENT
+
+This is a **living document** that should be updated throughout development to maintain accuracy.
+
+### Immediate Updates Required ⚠️
+
+Update **within the same session** when:
+
+- ✅ **New Components Added**: Add to Component Architecture table with dependencies and status
+- ✅ **Technology Stack Changes**: Update Technology Profile (framework version, new libraries, tools)
+- ✅ **API Changes**: Modify endpoint structure, add new APIs, change authentication method
+- ✅ **New Integrations**: Add external service integrations to Integration Points
+- ✅ **Architectural Refactoring**: Component reorganization, pattern changes, layer modifications
+- ✅ **Major Architectural Decisions**: Add to Technical Decisions Log with rationale
+- ✅ **Database Schema Changes**: Update Data Models, schema version, migration strategy
+- ✅ **Performance Baseline Changes**: Update after optimization or when targets change
+
+### Regular Updates (Weekly) ⏰
+
+Review and update during sprint planning or `/trinity-end`:
+
+- Component status changes (in development → testing → production)
+- Deployment environment updates
+- Monitoring and alerting configuration changes
+- Scaling strategy adjustments based on usage data
+- Security measures updates (new vulnerabilities addressed)
+
+### Quarterly Reviews 📅
+
+Deep architectural review and validation:
+
+- Architecture evolution planning (next quarter roadmap)
+- Technology constraint reassessment
+- Bottleneck analysis update
+- Migration path validation
+- Long-term improvement planning
+
+### Cross-Document Update Triggers 🔗
+
+**When updating ARCHITECTURE.md, also check:**
+
+- **[ISSUES.md](./ISSUES.md)**: Add known issues for new components, document architectural issues discovered
+- **[Technical-Debt.md](./Technical-Debt.md)**: Document architectural debt from shortcuts or legacy decisions
+- **[To-do.md](./To-do.md)**: Add tasks for incomplete architecture work (testing, documentation, monitoring)
+- **[CODING-PRINCIPLES.md](./CODING-PRINCIPLES.md)**: Update if component patterns establish new coding standards
+- **[TESTING-PRINCIPLES.md](./TESTING-PRINCIPLES.md)**: Update if new component types need new testing strategies
+
+### Update Scenarios - What to Change
+
+**Scenario: Added New Component**
+```yaml
+Updates_Required:
+  - Component_Architecture_Table: Add new row with component details
+  - Integration_Points: Add if component integrates with external services
+  - Data_Flow: Update if component processes data
+  - API_Architecture: Add if component exposes endpoints
+  - Testing_Architecture: Add component test strategy
+  - Cross_References:
+    - ISSUES.md: Document any known component issues
+    - To-do.md: Add component testing/documentation tasks
+```
+
+**Scenario: Framework/Technology Upgrade**
+```yaml
+Updates_Required:
+  - Technology_Profile: Update framework version and dependencies
+  - Framework_Specific_Architecture: Update patterns for new version
+  - Performance_Baselines: Re-benchmark with new framework
+  - Testing_Framework: Update test setup for new version
+  - Technical_Decisions_Log: Document upgrade rationale
+  - Migration_Path: Add upgrade steps for future reference
+  - Cross_References:
+    - Technical-Debt.md: Mark deprecated patterns as resolved
+    - CODING-PRINCIPLES.md: Update framework-specific examples
+```
+
+**Scenario: Performance Optimization**
+```yaml
+Updates_Required:
+  - Performance_Baselines: Update with new metrics
+  - Optimization_Strategies: Document what optimization was applied
+  - Monitoring_Points: Add new performance metrics if needed
+  - Bottleneck_Analysis: Update resolved bottlenecks
+  - Cross_References:
+    - Technical-Debt.md: Mark performance debt as resolved
+    - ISSUES.md: Close performance-related issues
+```
+
+**Scenario: New External Integration**
+```yaml
+Updates_Required:
+  - Integration_Points: Add external service details
+  - API_Architecture: Document integration API usage
+  - Security_Architecture: Add authentication/authorization for integration
+  - Deployment_Architecture: Add integration environment config
+  - Cross_References:
+    - To-do.md: Add integration testing tasks
+    - ISSUES.md: Document integration limitations/issues
+```
+
+### How to Update
+
+**Step-by-step process:**
+
+1. **Identify Section**: Find the relevant section based on what changed
+2. **Update Content**: Make specific changes (don't just update timestamp)
+3. **Verify Placeholders**: Ensure no `{{VARIABLE}}` syntax introduced
+4. **Check Cross-References**: Update related documents if needed
+5. **Update Timestamp**: Set `Last Updated: {{CURRENT_DATE}}` to actual date
+6. **Git Commit**: Commit with message like "docs: update ARCHITECTURE.md - added UserAuth component"
+
+**Quality Checklist:**
+- [ ] Changes are specific and meaningful (not generic)
+- [ ] All component names consistent across document
+- [ ] Cross-references to other files are valid
+- [ ] Metrics and values are from actual project (not examples)
+- [ ] Related documents updated (ISSUES, Technical-Debt, To-do)
+
+### When NOT to Update ❌
+
+**Don't update if:**
+- Only code comments changed (architecture unchanged)
+- Minor bug fixes that don't affect architecture
+- Code refactoring within existing components (no component changes)
+- Test additions that don't change test architecture
+- Documentation updates in code (no architectural documentation needed)
+
+**Stale timestamps are okay** if architecture genuinely hasn't changed. Don't update just to update.
+
+---
+
+**Document Status**: Living Documentation
+**Update Frequency**: As needed (session-based)
+**Maintained By**: Development team using Trinity Method
+**Referenced By**: `/trinity-end` command for session updates
+**Last Updated**: {{CURRENT_DATE}}