| name | architecture-documentation |
| description | C4 architecture model, security architecture, Mermaid diagrams, SECURITY_ARCHITECTURE.md, and comprehensive documentation per Hack23 Secure Development Policy |
| license | MIT |
Architecture Documentation Skill
Context
This skill applies when:
- Creating SECURITY_ARCHITECTURE.md for new repositories
- Documenting system architecture using C4 model
- Creating Mermaid diagrams for security architecture
- Planning future security architecture (FUTURE_SECURITY_ARCHITECTURE.md)
- Documenting data flows and trust boundaries
- Creating architecture decision records (ADRs)
- Conducting architecture reviews
This skill enforces Hack23 Secure Development Policy Section 🏗️ requirements for comprehensive architecture documentation.
Rules
1. C4 Architecture Model (Policy Section 📐)
- Level 1 - Context: System context with external dependencies
- Level 2 - Container: Applications, data stores, microservices
- Level 3 - Component: Internal components within containers
- Level 4 - Code: Implementation details (optional, for critical security)
2. Required Documentation Files (Policy Section 🏗️)
- SECURITY_ARCHITECTURE.md: Current security architecture
- FUTURE_SECURITY_ARCHITECTURE.md: Planned security improvements
- ARCHITECTURE.md: General system architecture
- DATA_FLOW.md: Data flow diagrams with classifications
- DEPLOYMENT.md: Deployment architecture and infrastructure
3. Mandatory Security Architecture Content (Policy Section 🏗️.3)
- Authentication & Authorization: Auth mechanisms and identity management
- Data Protection: Encryption, data classification, GDPR compliance
- Network Security: Network topology, VPCs, security groups
- Audit & Logging: Logging strategy, audit trails, SIEM integration
- Threat Model Integration: Links to threat model documentation
- Compliance Mapping: ISO 27001, NIST CSF, CIS Controls mapping
4. Mermaid Diagram Standards (Policy Section 🏗️)
- Color Coding: Red (untrusted), Green (trusted), Yellow (external), Blue (data)
- Trust Boundaries: Clearly marked trust boundaries
- Data Flow: Direction and data classification labels
- Security Controls: Security controls annotated on diagram
- Legend: Always include legend explaining symbols
Examples
✅ Good Pattern: SECURITY_ARCHITECTURE.md Template
# Security Architecture
**Project**: European Parliament MCP Server
**Classification**: Public with Personal Data
**Last Updated**: 2026-02-16
**Review Cycle**: Quarterly
## Executive Summary
The European Parliament MCP Server implements Model Context Protocol to provide secure access to European Parliament open data. Security architecture follows defense-in-depth principles with:
- Input validation at MCP tool boundaries
- GDPR-compliant data handling with 24-hour cache limits
- Audit logging for all personal data access
- Rate limiting to prevent abuse
## C4 Architecture Model
### Level 1: System Context
```mermaid
graph TB
User[End User<br/>Claude Desktop, VS Code]
subgraph "System Boundary"
EPMCP[European Parliament<br/>MCP Server]
end
EPAPI[European Parliament<br/>Open Data Portal<br/>data.europarl.europa.eu]
User -->|MCP Protocol<br/>stdio| EPMCP
EPMCP -->|HTTPS<br/>RESTful API| EPAPI
style User fill:#4a90e2
style EPMCP fill:#7cb342
style EPAPI fill:#ffa726
External Dependencies:
Level 2: Container Diagram
graph TB
Client[MCP Client<br/>Untrusted]
subgraph "MCP Server Process"
Transport["StdioServerTransport<br/>@modelcontextprotocol/sdk"]
Tools[Tool Handlers<br/>search_meps, get_mep]
Resources["Resource Handlers<br/>ep://meps/{id}"]
Prompts[Prompt Templates]
Validation[Input Validation<br/>Zod Schemas]
Cache[LRU Cache<br/>In-Memory]
Audit[Audit Logger]
end
EPAPI[European Parliament API<br/>External]
Client -->|JSON-RPC 2.0| Transport
Transport --> Validation
Validation --> Tools
Validation --> Resources
Validation --> Prompts
Tools --> Cache
Tools --> Audit
Tools -->|HTTPS| EPAPI
style Client fill:#ff6b6b
style Transport fill:#51cf66
style Tools fill:#51cf66
style Resources fill:#51cf66
style Prompts fill:#51cf66
style Validation fill:#51cf66
style Cache fill:#51cf66
style Audit fill:#51cf66
style EPAPI fill:#ffd43b
Level 3: Component Diagram (Tool Handler)
graph TB
Input[MCP Request]
subgraph "search_meps Tool"
Schema[SearchMEPsSchema<br/>Zod Validation]
RateLimit[Rate Limiter<br/>60 req/min]
CacheCheck[Cache Check<br/>LRU]
APIClient[EP API Client<br/>Undici]
Transform["Data Transform<br/>EP → MCP Format"]
AuditLog[GDPR Audit Log]
end
Output[MCP Response]
Input --> Schema
Schema -->|Valid| RateLimit
RateLimit --> CacheCheck
CacheCheck -->|Miss| APIClient
CacheCheck -->|Hit| Transform
APIClient --> Transform
Transform --> AuditLog
AuditLog --> Output
style Input fill:#4a90e2
style Schema fill:#51cf66
style RateLimit fill:#51cf66
style CacheCheck fill:#51cf66
style APIClient fill:#ffd43b
style Transform fill:#51cf66
style AuditLog fill:#51cf66
style Output fill:#4a90e2
Authentication & Authorization
MCP Protocol Security:
- Transport: stdio (no network exposure, process-level isolation)
- No authentication required (runs in user's local environment)
- Authorization: Process owner has full access
European Parliament API:
- Public API (no authentication required)
- Rate limiting via client-side implementation
- HTTPS with certificate validation mandatory
Data Protection
Data Classification
| Data Type | Classification | Retention | Encryption |
|---|
| MEP Names & Roles | Public | Cache 1h | None (public) |
| MEP Email/Phone | Personal Data | Cache 1h | TLS in transit |
| API Responses | Public | Cache 1-24h | TLS in transit |
| Audit Logs | Internal | 1 year | None (no PII in logs) |
GDPR Compliance
Data Minimization: Only collect public parliamentary data
Purpose Limitation: Parliamentary information queries only
Storage Limitation: Max 24-hour cache per GDPR-compliance skill
Audit Trail: All personal data access logged
Evidence: .github/skills/gdpr-compliance/SKILL.md
Network Security
Network Architecture: Node.js process, no inbound network connections
Communication Channels:
- stdin/stdout: MCP client communication (local IPC)
- HTTPS outbound: European Parliament API (TLS 1.3)
Security Controls:
- No open network ports
- HTTPS certificate validation
- DNS resolution via system resolver
Audit & Logging
Audit Events:
- Tool invocations (tool name, parameters)
- Personal data access (MEP ID, timestamp, purpose)
- Validation failures (invalid inputs, rejected requests)
- API errors (rate limits, timeouts, failures)
Log Format: Structured JSON to stderr
{
"timestamp": "2026-02-16T15:30:00.000Z",
"level": "info",
"event": "personal_data_access",
"mepId": 12345,
"purpose": "MCP tool invocation: search_meps",
"clientId": "claude-desktop"
}
Retention: 1 year minimum per ISMS policy
Threat Model Integration
Threat Model: THREAT_MODEL.md
Key Threats Addressed:
- Spoofing: Process-level isolation via stdio
- Tampering: Input validation with Zod schemas
- Repudiation: Comprehensive audit logging
- Information Disclosure: Safe error handling, no data in errors
- Denial of Service: Rate limiting, result size limits
- Elevation of Privilege: No privilege boundaries (single-user tool)
Compliance Mapping
ISO 27001:2022
| Control | Implementation | Evidence |
|---|
| A.8.3 (Handling of assets) | Input validation, data classification | src/validation/ |
| A.8.10 (Information deletion) | Cache TTL, GDPR erasure support | src/cache.ts |
| A.13.1.1 (Network controls) | HTTPS only, no open ports | src/api/client.ts |
| A.14.2.5 (Secure system engineering) | Defense-in-depth, threat modeling | THREAT_MODEL.md |
NIST CSF 2.0
| Function | Category | Implementation |
|---|
| PROTECT | PR.DS-01 (Data Security) | Encryption in transit, GDPR compliance |
| DETECT | DE.CM-01 (Continuous Monitoring) | Audit logging, error monitoring |
| RESPOND | RS.AN-01 (Analysis) | Error analysis, security incident tracking |
CIS Controls v8.1
| Control | Safeguard | Implementation |
|---|
| 3.3 (Configure Data Access Control Lists) | Basic | Zod validation, least privilege |
| 8.2 (Collect Audit Logs) | Basic | Structured audit logging |
| 16.10 (Apply Secure Design Principles) | Foundational | Defense-in-depth, fail-secure |
Security Controls Summary
graph TB
subgraph "Defense Layers"
L1["Layer 1: Input Validation<br/>Zod schemas, whitelist validation"]
L2["Layer 2: Rate Limiting<br/>60 req/min per client"]
L3["Layer 3: Caching<br/>LRU with TTL limits"]
L4["Layer 4: Audit Logging<br/>All data access logged"]
L5["Layer 5: Error Handling<br/>Safe errors, no data exposure"]
end
Request[Incoming Request] --> L1
L1 --> L2
L2 --> L3
L3 --> L4
L4 --> L5
L5 --> Response[Response]
style L1 fill:#51cf66
style L2 fill:#51cf66
style L3 fill:#51cf66
style L4 fill:#51cf66
style L5 fill:#51cf66
Future Security Architecture
See: FUTURE_SECURITY_ARCHITECTURE.md
Planned Improvements:
- Redis-based distributed cache (Q2 2026)
- OAuth 2.0 authentication for multi-user scenarios (Q3 2026)
- Prometheus metrics endpoint for monitoring (Q2 2026)
- OWASP ZAP integration in CI/CD (Q1 2026)
Review & Approval
Last Review: 2026-02-16
Next Review: 2026-05-16 (Quarterly)
Approved By: Security Team, CEO
**Policy Reference**: [Secure Development Policy Section 🏗️](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md#architecture-documentation-matrix)
**Evidence**:
- [CIA SECURITY_ARCHITECTURE.md](https://github.com/Hack23/cia/blob/master/SECURITY_ARCHITECTURE.md)
- [Black Trigram SECURITY_ARCHITECTURE.md](https://github.com/Hack23/blacktrigram/blob/main/SECURITY_ARCHITECTURE.md)
### ✅ Good Pattern: Mermaid Color Coding Standard
```mermaid
graph TB
subgraph Legend
Untrusted[Untrusted Zone<br/>External/User Input]
Trusted[Trusted Zone<br/>Validated/Internal]
External[External Service<br/>Third-party API]
Data[Data Store<br/>Database/Cache]
end
style Untrusted fill:#ff6b6b
style Trusted fill:#51cf66
style External fill:#ffd43b
style Data fill:#4a90e2
Color Standards:
- Red (#ff6b6b): Untrusted - user input, external clients
- Green (#51cf66): Trusted - validated components, internal services
- Yellow (#ffd43b): External - third-party APIs, external services
- Blue (#4a90e2): Data - databases, caches, data stores
✅ Good Pattern: Data Flow with Classification
graph LR
User[User Input<br/>Unclassified] -->|Validate| System[MCP Server]
System -->|Query| DB[Cache<br/>Personal Data]
DB -->|Retrieve| System
System -->|Response| User
System -->|Audit Log<br/>Internal| Logs[Audit Logs<br/>Internal]
style User fill:#ff6b6b
style System fill:#51cf66
style DB fill:#4a90e2
style Logs fill:#4a90e2
Anti-Patterns
❌ Bad: No Security Architecture Documentation
README.md exists, but no SECURITY_ARCHITECTURE.md
Why: Violates Secure Development Policy Section 🏗️ - All repos require security architecture documentation
❌ Bad: Diagram Without Trust Boundaries
graph LR
A --> B --> C --> D
Why: No color coding, no trust boundaries, no security context
Evidence Portfolio
Reference Implementations
-
Citizen Intelligence Agency (CIA)
-
Black Trigram Game
-
CIA Compliance Manager
Policy Documents
Architecture Documentation Checklist
ISMS Compliance
This skill enforces:
- SD-ARCH-001: Security architecture documentation requirements (
SECURITY_ARCHITECTURE.md, FUTURE_SECURITY_ARCHITECTURE.md)
- SD-ARCH-002: C4 model implementation standards (Context → Container → Component → Code)
- SD-ARCH-003: Mermaid diagram standards (accessibility, versioning, source-of-truth)
- SD-ARCH-004: Compliance-mapping requirements — each diagram cites controls
Policy References
Primary:
Related:
