605 lines
15 KiB
Markdown
605 lines
15 KiB
Markdown
# System Architecture
|
|
|
|
> Architecture diagrams and component documentation for Agent Guardrails Template
|
|
|
|
**Version:** 1.0
|
|
**Last Updated:** 2026-02-15
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [High-Level Architecture](#high-level-architecture)
|
|
2. [Component Diagram](#component-diagram)
|
|
3. [Data Flow](#data-flow)
|
|
4. [Team Structure](#team-structure)
|
|
5. [Deployment Architecture](#deployment-architecture)
|
|
6. [Integration Points](#integration-points)
|
|
|
|
---
|
|
|
|
## High-Level Architecture
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Client["Client Layer"]
|
|
CLI["CLI / Scripts"]
|
|
IDE["IDE Integration"]
|
|
CI["CI/CD Pipeline"]
|
|
end
|
|
|
|
subgraph MCP["MCP Layer"]
|
|
Server["MCP Server<br/>Port 8094"]
|
|
Router["Request Router"]
|
|
Validator["Input Validator"]
|
|
end
|
|
|
|
subgraph Tools["Tool Layer"]
|
|
TeamTools["Team Tools"]
|
|
GuardrailTools["Guardrail Tools"]
|
|
AgentTools["Agent Tools"]
|
|
end
|
|
|
|
subgraph Backend["Backend Layer (Go)"]
|
|
TeamMgr["Team Manager<br/>mcp-server/internal/team/"]
|
|
RuleEngine["Rule Engine<br/>mcp-server/internal/rules/"]
|
|
AuditLog["Audit Logger<br/>mcp-server/internal/audit/"]
|
|
end
|
|
|
|
subgraph Storage["Storage Layer"]
|
|
TeamConfig[".teams/*.json"]
|
|
Guardrails[".guardrails/"]
|
|
Logs[".mcp/logs/"]
|
|
end
|
|
|
|
CLI -->|HTTP/JSON-RPC| Server
|
|
IDE -->|HTTP/JSON-RPC| Server
|
|
CI -->|HTTP/JSON-RPC| Server
|
|
|
|
Server --> Router
|
|
Router --> Validator
|
|
Validator --> TeamTools
|
|
Validator --> GuardrailTools
|
|
Validator --> AgentTools
|
|
|
|
TeamTools --> TeamMgr
|
|
GuardrailTools --> RuleEngine
|
|
AgentTools --> TeamMgr
|
|
|
|
TeamMgr --> TeamConfig
|
|
TeamMgr --> AuditLog
|
|
RuleEngine --> Guardrails
|
|
AuditLog --> Logs
|
|
```
|
|
|
|
### Architecture Overview
|
|
|
|
The Agent Guardrails Template follows a layered architecture with clear separation of concerns:
|
|
|
|
> **Go Implementation:** All backend services are implemented in Go (v2.6.0+). See `mcp-server/internal/`.
|
|
|
|
| Layer | Responsibility | Components |
|
|
|-------|---------------|------------|
|
|
| Client | Interface with users | CLI, IDE, CI/CD |
|
|
| MCP | Protocol handling | Server, routing, validation |
|
|
| Tools | Business logic | Team, guardrail, agent operations |
|
|
| Backend | Core services (Go) | Team manager, rules engine, audit logger |
|
|
| Storage | Persistence | PostgreSQL, Redis, JSON configs |
|
|
|
|
---
|
|
|
|
## Component Diagram
|
|
|
|
### MCP Server Components
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph MCP_Server["MCP Server"]
|
|
direction TB
|
|
|
|
subgraph Transport["Transport Layer"]
|
|
HTTP["HTTP Listener<br/>Port 8094"]
|
|
JSONRPC["JSON-RPC Handler"]
|
|
end
|
|
|
|
subgraph Core["Core Services"]
|
|
Session["Session Manager"]
|
|
ToolReg["Tool Registry"]
|
|
Middleware["Middleware Stack"]
|
|
end
|
|
|
|
subgraph Tools["Available Tools"]
|
|
T1["guardrail_team_init"]
|
|
T2["guardrail_team_list"]
|
|
T3["guardrail_team_assign"]
|
|
T4["guardrail_team_unassign"]
|
|
T5["guardrail_team_status"]
|
|
T6["guardrail_phase_gate_check"]
|
|
T7["guardrail_agent_team_map"]
|
|
T8["guardrail_team_size_validate"]
|
|
T9["guardrail_validate_bash"]
|
|
T10["guardrail_validate_git_operation"]
|
|
T11["guardrail_validate_file_edit"]
|
|
end
|
|
end
|
|
|
|
HTTP --> JSONRPC
|
|
JSONRPC --> Session
|
|
Session --> Middleware
|
|
Middleware --> ToolReg
|
|
ToolReg --> T1
|
|
ToolReg --> T2
|
|
ToolReg --> T3
|
|
ToolReg --> T4
|
|
ToolReg --> T5
|
|
ToolReg --> T6
|
|
ToolReg --> T7
|
|
ToolReg --> T8
|
|
ToolReg --> T9
|
|
ToolReg --> T10
|
|
ToolReg --> T11
|
|
```
|
|
|
|
### Team Manager Components
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Team_Manager["Team Manager"]
|
|
direction TB
|
|
|
|
API["API Layer"]
|
|
|
|
subgraph Business_Logic["Business Logic"]
|
|
Init["Initialize Teams"]
|
|
Assign["Assign/Unassign"]
|
|
Validate["Validate Teams"]
|
|
Status["Check Status"]
|
|
Gates["Phase Gates"]
|
|
end
|
|
|
|
subgraph Data_Access["Data Access"]
|
|
ConfigLoader["Config Loader"]
|
|
ConfigWriter["Config Writer"]
|
|
Validator["Data Validator"]
|
|
end
|
|
|
|
subgraph Models["Team Models"]
|
|
Team["Team (1-12)"]
|
|
Role["Role"]
|
|
Member["Member"]
|
|
Phase["Phase (1-5)"]
|
|
end
|
|
end
|
|
|
|
API --> Business_Logic
|
|
Init --> ConfigWriter
|
|
Assign --> ConfigWriter
|
|
Validate --> ConfigLoader
|
|
Status --> ConfigLoader
|
|
Gates --> ConfigLoader
|
|
|
|
ConfigLoader --> Models
|
|
ConfigWriter --> Models
|
|
Validator --> Models
|
|
```
|
|
|
|
---
|
|
|
|
## Data Flow
|
|
|
|
### Tool Execution Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client as Client
|
|
participant Server as MCP Server
|
|
participant Validator as Input Validator
|
|
participant Tool as Tool Handler
|
|
participant Backend as Backend Service
|
|
participant Storage as Storage
|
|
|
|
Client->>Server: HTTP POST /mcp/v1/message
|
|
Server->>Server: Parse JSON-RPC request
|
|
Server->>Validator: Validate input parameters
|
|
|
|
alt Validation Failed
|
|
Validator-->>Server: ValidationError
|
|
Server-->>Client: 400 Bad Request
|
|
else Validation Passed
|
|
Validator->>Tool: Route to tool handler
|
|
Tool->>Backend: Execute business logic
|
|
Backend->>Storage: Read/Write data
|
|
Storage-->>Backend: Data response
|
|
Backend-->>Tool: Operation result
|
|
Tool-->>Server: Tool response
|
|
Server-->>Client: 200 OK + result
|
|
end
|
|
```
|
|
|
|
### Team Assignment Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client as Client
|
|
participant Server as MCP Server
|
|
participant TeamTool as Team Tool
|
|
participant TeamMgr as Team Manager
|
|
participant File as .teams/{project}.json
|
|
|
|
Client->>Server: guardrail_team_assign
|
|
Server->>TeamTool: Route request
|
|
TeamTool->>TeamTool: Validate parameters
|
|
|
|
alt Invalid Parameters
|
|
TeamTool-->>Server: Error: TEAM-002/TEAM-003
|
|
else Valid Parameters
|
|
TeamTool->>TeamMgr: assign_role(project, team, role, person)
|
|
TeamMgr->>File: Read current config
|
|
File-->>TeamMgr: Team configuration
|
|
|
|
alt Team Full
|
|
TeamMgr-->>TeamTool: Error: TEAM-005
|
|
else Role Occupied
|
|
TeamMgr-->>TeamTool: Error: TEAM-004
|
|
else Success
|
|
TeamMgr->>File: Write updated config
|
|
TeamMgr->>TeamMgr: Log audit event
|
|
TeamMgr-->>TeamTool: Assignment confirmed
|
|
end
|
|
end
|
|
|
|
TeamTool-->>Server: Response
|
|
Server-->>Client: JSON-RPC result
|
|
```
|
|
|
|
### Phase Gate Check Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client as Client
|
|
participant Server as MCP Server
|
|
participant GateTool as Phase Gate Tool
|
|
participant TeamMgr as Team Manager
|
|
participant Rules as .guardrails/team-layout-rules.json
|
|
participant Config as .teams/{project}.json
|
|
|
|
Client->>Server: guardrail_phase_gate_check
|
|
Server->>GateTool: Route request
|
|
GateTool->>Rules: Load gate requirements
|
|
Rules-->>GateTool: Gate rules
|
|
|
|
GateTool->>TeamMgr: Get phase status
|
|
TeamMgr->>Config: Read team config
|
|
Config-->>TeamMgr: All team data
|
|
|
|
TeamMgr-->>GateTool: Phase status summary
|
|
|
|
GateTool->>GateTool: Compare requirements vs actual
|
|
|
|
alt Gate Requirements Met
|
|
GateTool-->>Server: Gate approved, can proceed
|
|
else Gate Requirements Not Met
|
|
GateTool-->>Server: Missing deliverables list
|
|
end
|
|
|
|
Server-->>Client: Gate check result
|
|
```
|
|
|
|
---
|
|
|
|
## Team Structure
|
|
|
|
### 12-Team Organization
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Phase1["Phase 1: Strategy & Planning"]
|
|
T1["Team 1<br/>Business & Product<br/>Strategy"]
|
|
T2["Team 2<br/>Enterprise<br/>Architecture"]
|
|
T3["Team 3<br/>GRC"]
|
|
end
|
|
|
|
subgraph Phase2["Phase 2: Platform & Foundation"]
|
|
T4["Team 4<br/>Infrastructure &<br/>Cloud Ops"]
|
|
T5["Team 5<br/>Platform<br/>Engineering"]
|
|
T6["Team 6<br/>Data Governance &<br/>Analytics"]
|
|
end
|
|
|
|
subgraph Phase3["Phase 3: The Build Squads"]
|
|
T7["Team 7<br/>Core Feature<br/>Squad"]
|
|
T8["Team 8<br/>Middleware &<br/>Integration"]
|
|
end
|
|
|
|
subgraph Phase4["Phase 4: Validation & Hardening"]
|
|
T9["Team 9<br/>Cybersecurity<br/>AppSec"]
|
|
T10["Team 10<br/>Quality<br/>Engineering"]
|
|
end
|
|
|
|
subgraph Phase5["Phase 5: Delivery & Sustainment"]
|
|
T11["Team 11<br/>Site Reliability<br/>Engineering"]
|
|
T12["Team 12<br/>IT Operations &<br/>Support"]
|
|
end
|
|
|
|
Phase1 -->|Gate 1| Phase2
|
|
Phase2 -->|Gate 2| Phase3
|
|
Phase3 -->|Gate 3| Phase4
|
|
Phase4 -->|Gate 4| Phase5
|
|
```
|
|
|
|
### Phase Gate Flow
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph Gates["Phase Gates"]
|
|
direction LR
|
|
|
|
G1["Gate 1<br/>Architecture<br/>Review Board"]
|
|
G2["Gate 2<br/>Environment<br/>Readiness"]
|
|
G3["Gate 3<br/>Feature Complete"]
|
|
G4["Gate 4<br/>Security + QA<br/>Sign-off"]
|
|
end
|
|
|
|
P1["Phase 1<br/>Strategy"] --> G1 --> P2["Phase 2<br/>Platform"]
|
|
P2 --> G2 --> P3["Phase 3<br/>Build"]
|
|
P3 --> G3 --> P4["Phase 4<br/>Validate"]
|
|
P4 --> G4 --> P5["Phase 5<br/>Deliver"]
|
|
```
|
|
|
|
---
|
|
|
|
## Deployment Architecture
|
|
|
|
### Single Node Deployment
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Server["Single Server"]
|
|
subgraph Docker["Docker Container"]
|
|
MCP["MCP Server<br/>Port 8094"]
|
|
Scripts["Team Manager Scripts"]
|
|
end
|
|
|
|
subgraph Volume1["Config Volume"]
|
|
Teams[".teams/"]
|
|
Guardrails[".guardrails/"]
|
|
end
|
|
|
|
subgraph Volume2["Log Volume"]
|
|
Logs[".mcp/logs/"]
|
|
end
|
|
end
|
|
|
|
Client["Client"]
|
|
|
|
Client -->|HTTP| MCP
|
|
MCP --> Scripts
|
|
Scripts --> Teams
|
|
Scripts --> Guardrails
|
|
MCP --> Logs
|
|
```
|
|
|
|
### Production Deployment
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Clients["Client Layer"]
|
|
CLI["CLI Tools"]
|
|
IDEs["IDE Extensions"]
|
|
CICD["CI/CD Runners"]
|
|
end
|
|
|
|
subgraph LB["Load Balancer"]
|
|
Nginx["Nginx / ALB"]
|
|
end
|
|
|
|
subgraph AppServers["Application Servers"]
|
|
S1["MCP Server 1"]
|
|
S2["MCP Server 2"]
|
|
S3["MCP Server 3"]
|
|
end
|
|
|
|
subgraph SharedStorage["Shared Storage"]
|
|
NFS["NFS / EFS"]
|
|
Teams["Team Configs"]
|
|
Rules["Guardrail Rules"]
|
|
end
|
|
|
|
subgraph Database["Database"]
|
|
Postgres[(PostgreSQL)]
|
|
Audit["Audit Logs"]
|
|
end
|
|
|
|
subgraph Monitoring["Monitoring"]
|
|
Prometheus["Prometheus"]
|
|
Grafana["Grafana"]
|
|
end
|
|
|
|
CLI -->|HTTPS| Nginx
|
|
IDEs -->|HTTPS| Nginx
|
|
CICD -->|HTTPS| Nginx
|
|
|
|
Nginx --> S1
|
|
Nginx --> S2
|
|
Nginx --> S3
|
|
|
|
S1 --> NFS
|
|
S2 --> NFS
|
|
S3 --> NFS
|
|
|
|
S1 --> Postgres
|
|
S2 --> Postgres
|
|
S3 --> Postgres
|
|
|
|
S1 --> Prometheus
|
|
S2 --> Prometheus
|
|
S3 --> Prometheus
|
|
|
|
NFS --> Teams
|
|
NFS --> Rules
|
|
Postgres --> Audit
|
|
```
|
|
|
|
---
|
|
|
|
## Integration Points
|
|
|
|
### External System Integrations
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph AGT["Agent Guardrails Template"]
|
|
MCP["MCP Server"]
|
|
Scripts["Management Scripts"]
|
|
end
|
|
|
|
subgraph External["External Systems"]
|
|
Git["Git Provider<br/>GitHub/GitLab"]
|
|
CI["CI/CD<br/>Jenkins/Actions"]
|
|
Auth["Auth Provider<br/>OAuth/SAML"]
|
|
Monitor["Monitoring<br/>Datadog/NewRelic"]
|
|
end
|
|
|
|
subgraph AI["AI Assistants"]
|
|
Claude["Claude Code"]
|
|
OpenCode["OpenCode"]
|
|
Cursor["Cursor"]
|
|
end
|
|
|
|
MCP <-->|Git Operations| Git
|
|
MCP <-->|Pipeline Triggers| CI
|
|
MCP <-->|Authentication| Auth
|
|
Scripts <-->|Metrics Export| Monitor
|
|
|
|
Claude <-->|MCP Protocol| MCP
|
|
OpenCode <-->|MCP Protocol| MCP
|
|
Cursor <-->|MCP Protocol| MCP
|
|
```
|
|
|
|
### API Integration Patterns
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Integration["Integration Patterns"]
|
|
direction TB
|
|
|
|
P1["Synchronous<br/>Request/Response"]
|
|
P2["Asynchronous<br/>Webhook"]
|
|
P3["Batch<br/>File-based"]
|
|
end
|
|
|
|
subgraph UseCases["Use Cases"]
|
|
UC1["Team Assignments"]
|
|
UC2["Phase Gate Checks"]
|
|
UC3["Validation"]
|
|
UC4["Audit Export"]
|
|
UC5["Bulk Updates"]
|
|
end
|
|
|
|
P1 --> UC1
|
|
P1 --> UC2
|
|
P1 --> UC3
|
|
P2 --> UC4
|
|
P3 --> UC5
|
|
```
|
|
|
|
---
|
|
|
|
## Security Architecture
|
|
|
|
### Authentication Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client as Client
|
|
participant Server as MCP Server
|
|
participant Auth as Auth Service
|
|
participant Tool as Tool Handler
|
|
|
|
Client->>Server: Request + API Key
|
|
Server->>Auth: Validate API Key
|
|
|
|
alt Invalid Key
|
|
Auth-->>Server: 401 Unauthorized
|
|
Server-->>Client: AUTH-002 Error
|
|
else Valid Key
|
|
Auth-->>Server: User + Permissions
|
|
Server->>Server: Check permissions
|
|
|
|
alt Insufficient Permissions
|
|
Server-->>Client: AUTH-003 Error
|
|
else Authorized
|
|
Server->>Tool: Execute request
|
|
Tool-->>Server: Result
|
|
Server-->>Client: Success response
|
|
end
|
|
end
|
|
```
|
|
|
|
### Data Protection
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Security["Security Layers"]
|
|
L1["Input Validation<br/>Sanitization"]
|
|
L2["Authentication<br/>Authorization"]
|
|
L3["Audit Logging<br/>Non-repudiation"]
|
|
L4["Encryption<br/>At Rest & Transit"]
|
|
end
|
|
|
|
subgraph Threats["Threat Mitigation"]
|
|
T1["Injection Attacks"]
|
|
T2["Unauthorized Access"]
|
|
T3["Data Tampering"]
|
|
T4["Data Breach"]
|
|
end
|
|
|
|
L1 --> T1
|
|
L2 --> T2
|
|
L3 --> T3
|
|
L4 --> T4
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration Architecture
|
|
|
|
> **Go Implementation:** All backend logic is implemented in Go. See `mcp-server/internal/` for package structure.
|
|
> **Migration:** `team_manager.py` has been migrated to Go (v2.6.0). See [PYTHON_MIGRATION.md](PYTHON_MIGRATION.md).
|
|
|
|
### File Organization
|
|
|
|
```
|
|
/mnt/ollama/git/agent-guardrails-template/
|
|
├── mcp-server/
|
|
│ ├── internal/ # Go implementation
|
|
│ │ ├── team/ # Team management logic
|
|
│ │ ├── rules/ # Rule engine
|
|
│ │ ├── audit/ # Audit logging
|
|
│ │ ├── database/ # Database operations
|
|
│ │ ├── cache/ # Redis caching
|
|
│ │ ├── mcp/ # MCP protocol
|
|
│ │ └── web/ # HTTP handlers
|
|
│ └── cmd/server/ # Main entry point
|
|
├── .teams/
|
|
│ ├── {project-name}.json # Team configurations
|
|
│ └── backups/
|
|
│ └── *.json.bak # Automatic backups
|
|
├── .guardrails/
|
|
│ ├── rules.json # Validation rules
|
|
│ ├── team-layout-rules.json # Team structure rules
|
|
│ └── schemas/
|
|
│ └── team-config.schema.json # JSON Schema
|
|
├── .mcp/
|
|
│ ├── mcp.log # Server logs
|
|
│ ├── audit.log # Security audit logs
|
|
│ └── config.json # Server configuration
|
|
└── scripts/
|
|
└── setup_agents.py # Agent setup (Python - legacy)
|
|
```
|
|
|
|
---
|
|
|
|
**Last Updated:** 2026-02-15
|
|
**Version:** 2.6.0
|
|
**Implementation:** Go (mcp-server/internal/)
|