documentation-portfolio

# Documentation Portfolio Skill ## Purpose This skill defines the complete set of architecture documentation required for Hack23 projects. It ensures comprehensive documentation that supports both current operations and future planning, following best practices for technical documentation. ## Rules ### Required Documentation Files **MUST CREATE** for each project: #### Current State Documentation - `ARCHITECTURE.md` - C4 model diagrams (Context, Container, Component) - `DATA_MODEL.md` - Database schema, entity relationships - `FLOWCHART.md` - Process flows and workflows - `STATEDIAGRAM.md` - State machines and transitions - `MINDMAP.md` - System concepts and relationships - `SWOT.md` - Strengths, Weaknesses, Opportunities, Threats analysis #### Future State Documentation - `FUTURE_ARCHITECTURE.md` - Planned architecture changes - `FUTURE_DATA_MODEL.md` - Planned data model evolution - `FUTURE_FLOWCHART.md` - Planned process improvements - `FUTURE_STATEDIAGRAM.md` - Planned state machine changes - `FUTURE_MINDMAP.md` - Future vision and concepts - `FUTURE_SWOT.md` - Future state SWOT analysis #### Security Documentation - `SECURITY_ARCHITECTURE.md` - Security controls and architecture - `FUTURE_SECURITY_ARCHITECTURE.md` - Planned security improvements - `THREAT_MODEL.md` - Threat analysis and mitigations #### Supplementary Documentation - `README.md` - Project overview, getting started - `.github/SECURITY.md` - Vulnerability reporting - `CONTRIBUTING.md` - Contribution guidelines - `CLASSIFICATION.md` - Data classification guidance (if applicable) - `ADR/` directory - Architecture Decision Records ### Documentation Standards **MUST:** - Write in Markdown format - Use Mermaid for all diagrams - Include table of contents for documents > 500 lines - Add last updated date at top of document - Link related documents - Version documents (use git for versioning) - Keep diagrams up-to-date with code - Review documentation quarterly **MUST NOT:** - Include sensitive information (secrets, credentials) - Create stale documentation (update or delete) - Duplicate information across documents (link instead) - Use proprietary diagram formats (use Mermaid) ### ARCHITECTURE.md Structure **MUST INCLUDE:** 1. **Overview** - System purpose and scope 2. **System Context Diagram** - C4 Level 1 3. **Container Diagram** - C4 Level 2 4. **Component Diagrams** - C4 Level 3 (for key containers) 5. **Technology Stack** - Languages, frameworks, services 6. **Deployment Architecture** - How system is deployed 7. **Integration Points** - External systems and APIs 8. **Architecture Decision Records** - Links to ADRs ### DATA_MODEL.md Structure **MUST INCLUDE:** 1. **Overview** - Data model purpose 2. **Entity Relationship Diagram** - Mermaid ER diagram 3. **Entity Descriptions** - Each entity with attributes 4. **Relationships** - Cardinality and constraints 5. **Indexes** - Performance-critical indexes 6. **Data Classification** - Sensitivity of each entity/attribute 7. **Data Retention** - How long data is kept ### FLOWCHART.md Structure **MUST INCLUDE:** 1. **Overview** - Processes documented 2. **Key Workflows** - Main user/system flows 3. **Flowchart Diagrams** - Mermaid flowcharts 4. **Decision Points** - Logic branches explained 5. **Error Handling** - Exception flows 6. **Performance Considerations** - Bottlenecks, optimizations ### STATEDIAGRAM.md Structure **MUST INCLUDE:** 1. **Overview** - State machines in system 2. **State Diagrams** - Mermaid state diagrams 3. **States** - Description of each state 4. **Transitions** - Events that trigger transitions 5. **State Invariants** - What must be true in each state 6. **Terminal States** - End states and cleanup ### MINDMAP.md Structure **MUST INCLUDE:** 1. **Overview** - Purpose of mindmap 2. **Core Concepts** - Central ideas 3. **Mindmap Diagram** - Mermaid mindmap 4. **Concept Descriptions** - Explanation of each node 5. **Relationships** - How concepts connect 6. **Use Cases** - How mindmap aids understanding ### SWOT.md Structure **MUST INCLUDE:** 1. **Overview** - Context for SWOT analysis 2. **Strengths** - Internal positive attributes 3. **Weaknesses** - Internal limitations 4. **Opportunities** - External favorable factors 5. **Threats** - External risks 6. **Strategy Matrix** - How to leverage/address SWOT 7. **Action Items** - Concrete next steps ## Examples ### Example 1: DATA_MODEL.md Structure ```markdown # Data Model - Hack23 CIA Platform **Last Updated:** 2025-01-24 ## Overview This document describes the data model for the Citizen Intelligence Agency platform, which stores political data including politicians, parties, votes, and documents. ## Entity Relationship Diagram ```mermaid erDiagram POLITICIAN ||--o{ POLITICIAN_ROLE : has POLITICIAN ||--o{ VOTE : casts POLITICIAN }|--|| PARTY : "member of" PARTY ||--o{ VOTE : "party line" PARTY ||--o{ DOCUMENT : publishes BALLOT ||--o{ VOTE : contains BALLOT }|--|| COMMITTEE : "voted in" DOCUMENT }|--o| POLITICIAN : authored DOCUMENT }|--o| PARTY : published POLITICIAN { uuid id PK string personId UK "Unique ID from Riksdagen" string firstName string lastName date birthDate string gender timestamp createdAt timestamp updatedAt } PARTY { uuid id PK string partyId UK string name string abbreviation string website timestamp createdAt } POLITICIAN_ROLE { uuid id PK uuid politicianId FK string roleType "MP, Minister, etc" date fromDate date toDate string details } VOTE { uuid id PK uuid ballotId FK uuid politicianId FK string voteOption "Yes, No, Abstain, Absent" timestamp voteTime } BALLOT { uuid id PK string ballotId UK string title string description date voteDate uuid committeeId FK timestamp createdAt } DOCUMENT { uuid id PK string documentId UK string title string documentType string status date publishedDate uuid authorId FK uuid partyId FK } COMMITTEE { uuid id PK string committeeId UK string name string abbreviation } ``` ## Entity Descriptions ### POLITICIAN Stores information about Swedish politicians. | Attribute | Type | Classification | Description | |-----------|------|---------------|-------------| | id | UUID | INTERNAL | Primary key | | personId | String | PUBLIC | Unique ID from Riksdagen API | | firstName | String | PUBLIC | First name | | lastName | String | PUBLIC | Last name | | birthDate | Date | PUBLIC | Date of birth | | gender | String | PUBLIC | Gender (M/F) | | createdAt | Timestamp | INTERNAL | Record creation time | | updatedAt | Timestamp | INTERNAL | Last update time | **Indexes:** - `idx_politician_person_id` (UNIQUE) on `personId` - `idx_politician_name` on `lastName, firstName` **Data Retention:** Indefinite (historical political data) ### VOTE Records individual votes cast by politicians. | Attribute | Type | Classification | Description | |-----------|------|---------------|-------------| | id | UUID | INTERNAL | Primary key | | ballotId | UUID | INTERNAL | Foreign key to BALLOT | | politicianId | UUID | INTERNAL | Foreign key to POLITICIAN | | voteOption | String | PUBLIC | Yes/No/Abstain/Absent | | voteTime | Timestamp | PUBLIC | When vote was cast | **Indexes:** - `idx_vote_ballot` on `ballotId` - `idx_vote_politician` on `politicianId` - `idx_vote_time` on `voteTime` **Data Retention:** Indefinite (historical voting records) ## Relationships - **POLITICIAN to PARTY**: Many-to-One (politician belongs to one party at a time) - **POLITICIAN to VOTE**: One-to-Many (politician casts many votes) - **BALLOT to VOTE**: One-to-Many (ballot contains many votes) - **POLITICIAN to POLITICIAN_ROLE**: One-to-Many (politician has multiple roles over time) ## Data Classification Summary - **PUBLIC**: Politician names, votes, documents (public record) - **INTERNAL**: System IDs, timestamps, technical metadata - **CONFIDENTIAL**: None - **RESTRICTED**: None ## Performance Considerations - Votes table will grow large (millions of records), requires partitioning by year - Full-text search on DOCUMENT requires Elasticsearch integration - POLITICIAN queries often join with PARTY, consider denormalization for read performance ## Migration Strategy See `FUTURE_DATA_MODEL.md` for planned schema changes. ``` ### Example 2: FLOWCHART.md Structure ```markdown # Flowcharts - Hack23 Homepage Deployment **Last Updated:** 2025-01-24 ## Overview This document describes the key workflows and processes for the Hack23 Homepage, focusing on content updates, deployment, and monitoring. ## Content Update Workflow ```mermaid flowchart TD Start([Developer creates PR]) --> Validate{Validation checks pass?} Validate -->|No| Fix[Fix errors] Fix --> Start Validate -->|Yes| Review[Code review] Review --> Approved{Approved?} Approved -->|No| RequestChanges[Request changes] RequestChanges --> Start Approved -->|Yes| Merge[Merge to main] Merge --> Build[Build & Minify] Build --> Security[Security scan - ZAP] Security --> SecurityPass{Vulnerabilities found?} SecurityPass -->|Yes| Alert[Create security issue] Alert --> Block[Block deployment] Block --> End1([End - Deployment blocked]) SecurityPass -->|No| Lighthouse[Lighthouse audit] Lighthouse --> LighthousePass{Meets budget?} LighthousePass -->|No| Warning[Warning - below threshold] Warning --> DeployAnyway{Deploy anyway?} DeployAnyway -->|No| End2([End - Deployment cancelled]) DeployAnyway -->|Yes| Deploy[Deploy to S3] LighthousePass -->|Yes| Deploy Deploy --> Invalidate[Invalidate CloudFront cache] Invalidate --> Verify[Verify deployment] Verify --> Success{Deployment successful?} Success -->|Yes| Notify[Notify team - Success] Success -->|No| Rollback[Rollback deployment] Rollback --> NotifyFail[Notify team - Failure] NotifyFail --> End3([End - Rolled back]) Notify --> End4([End - Deployed successfully]) ``` ## Translation Workflow ```mermaid flowchart TD Start([New content in English]) --> Detect[Detect languages to translate] Detect --> Generate[Generate translations] Generate --> Review{Translation quality check} Review -->|Low quality| Manual[Manual translation] Manual --> Validate Review -->|Good quality| Validate[Validate HTML structure] Validate --> ValidPass{Valid HTML?} ValidPass -->|No| Fix[Fix validation errors] Fix --> Validate ValidPass -->|Yes| Hreflang[Update hreflang tags] Hreflang --> Sitemap[Update sitemap.xml] Sitemap --> Test[Test translated pages] Test --> TestPass{All tests pass?} TestPass -->|No| Debug[Debug issues] Debug --> Fix TestPass -->|Yes| Commit[Commit translations] Commit --> End([End - Translations complete]) ``` ## Security Incident Response ```mermaid flowchart TD Start([Security incident detected]) --> Assess[Assess severity] Assess --> Critical{Critical incident?} Critical -->|Yes| Immediate[Immediate response team] Immediate --> Block[Block attack vector] Block --> Contain[Contain incident] Critical -->|No| Standard[Standard response] Standard --> Investigate[Investigate incident] Contain --> Investigate Investigate --> Determine{Cause identified?} Determine -->|No| Escalate[Escalate to security team] Escalate --> Investigate Determine -->|Yes| Remediate[Implement fix] Remediate --> Test[Test remediation] Test --> TestPass{Incident resolved?} TestPass -->|No| Remediate TestPass -->|Yes| Deploy[Deploy fix] Deploy --> Monitor[Monitor for recurrence] Monitor --> Document[Document incident] Document --> Review[Post-incident review] Review --> Improve[Improve security controls] Improve --> End([End - Incident resolved]) ``` ## Decision Points ### Validation Checks - HTML validation - CSS validation - JavaScript linting - Accessibility checks (WCAG 2.1 AA) - Link validation - Security header validation ### Security Scan Thresholds - **Block deployment**: Critical vulnerabilities - **Warning**: High vulnerabilities (review required) - **Pass**: Medium or lower vulnerabilities ### Lighthouse Budget - Performance: ≥ 90 - Accessibility: ≥ 95 - Best Practices: ≥ 95 - SEO: ≥ 95 ## Error Handling All workflows include error handling: 1. **Detect error** - Automated checks or manual report 2. **Log error** - CloudWatch, GitHub Actions logs 3. **Notify** - Slack/email notification 4. **Rollback** (if deployed) - Revert to previous version 5. **Fix** - Implement correction 6. **Verify** - Test fix before re-deploying ## Performance Considerations - **Parallel processing**: Run security scan and Lighthouse audit in parallel - **Caching**: Cache CloudFront invalidation to avoid rate limits - **Incremental builds**: Only process changed files ```