بنقرة واحدة
architecture-documentation
// C4 architecture model, security architecture, Mermaid diagrams, SECURITY_ARCHITECTURE.md, and comprehensive documentation per Hack23 Secure Development Policy
// C4 architecture model, security architecture, Mermaid diagrams, SECURITY_ARCHITECTURE.md, and comprehensive documentation per Hack23 Secure Development Policy
AI-augmented development controls, GitHub Copilot governance, LLM security, AI-generated code review per Hack23 Secure Development Policy
EU AI Act compliance, OWASP LLM security, responsible AI practices for parliamentary data and MCP server applications
Enforce code quality with ESLint, TypeScript strict mode, Knip unused detection, and quality gates for MCP servers
ISO 27001, NIST CSF 2.0, CIS Controls v8.1, EU CRA compliance mapping, multi-standard alignment per Hack23 ISMS policies
Contribution process with PR workflow, code review standards, commit conventions, and open source best practices
Clear technical documentation with JSDoc, READMEs, Mermaid diagrams, ISMS policy references, and comprehensive code examples
| name | architecture-documentation |
| description | C4 architecture model, security architecture, Mermaid diagrams, SECURITY_ARCHITECTURE.md, and comprehensive documentation per Hack23 Secure Development Policy |
| license | MIT |
This skill applies when:
This skill enforces Hack23 Secure Development Policy Section 🏗️ requirements for comprehensive architecture documentation.
# 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:
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
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
MCP Protocol Security:
European Parliament API:
| 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) |
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 Architecture: Node.js process, no inbound network connections
Communication Channels:
Security Controls:
Audit Events:
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: THREAT_MODEL.md
Key Threats Addressed:
| 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 |
| 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 |
| 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 |
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
See: FUTURE_SECURITY_ARCHITECTURE.md
Planned Improvements:
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:
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
README.md exists, but no SECURITY_ARCHITECTURE.md
Why: Violates Secure Development Policy Section 🏗️ - All repos require security architecture documentation
graph LR
A --> B --> C --> D
Why: No color coding, no trust boundaries, no security context
Citizen Intelligence Agency (CIA)
Black Trigram Game
CIA Compliance Manager
This skill enforces:
SECURITY_ARCHITECTURE.md, FUTURE_SECURITY_ARCHITECTURE.md)Primary:
Related:
DATA_MODEL.md / FLOWCHART.md