# oskarbartoszyk/masqe-hackyeah2026 architecture

> Architecture diagram of the GitHub repository oskarbartoszyk/masqe-hackyeah2026, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oskarbartoszyk/masqe-hackyeah2026
- Repository: https://github.com/oskarbartoszyk/masqe-hackyeah2026

## Overview

MASQE is a runtime security gateway for agent actions. Clients submit actions through the Go gateway, which evaluates policy and defenses, executes only permitted actions, inspects results, and records decisions for audit and reporting. Python services provide semantic scoring, PII detection, explanations, and Ghost Shell support; the Go gateway remains the decision authority. The dashboard exposes operations, events, incidents, policy, agent activity, and Ghost sessions. Some Go and dashboard subsystem links reflect README documentation because their implementation excerpts were not shown.

Main entry points: [`gateway/engine.go`](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/engine.go) (Decision engine), [`dashboard/src/App.jsx`](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/App.jsx) (Console application), [`dashboard/src/lib.js`](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/lib.js) (Console API client), [`gateway/server.go`](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/server.go) (HTTP gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Client integrations"]
  node_sdk["Python SDK<br/>[masqe_sdk.py]"]
  node_mcp["MCP proxy<br/>[masqe_mcp.py]"]
end

subgraph group_gateway["Go security gateway"]
  node_gateway_server["HTTP gateway<br/>[server.go]"]
  node_engine["Decision engine<br/>[engine.go]"]
  node_execution["Action execution<br/>[execution.go]"]
  node_guards["Deterministic guards<br/>[guards.go]"]
end

subgraph group_guard["Python guard services"]
  node_semantic["Semantic scoring<br/>[server.py]"]
  node_pii["PII detection<br/>[ner_service.py]"]
  node_ner_model["NER engine<br/>[ner.py]"]
  node_pii_rules["PII rules and spans<br/>[rules.py]"]
  node_explain["Decision explanations<br/>[explain.py]"]
  node_ghost["Ghost Shell<br/>[ghost.py]"]
end

subgraph group_state["Audit and policy state"]
  node_policy["Policy and threat feed<br/>[config.go]"]
  node_store[("Audit store<br/>[store.go]")]
  node_audit_chain["Tamper-evident chain<br/>[audit_chain.go]"]
  node_telemetry["Telemetry and traces<br/>[telemetry.go]"]
end

subgraph group_console["Security console"]
  node_dashboard["Console application<br/>[App.jsx]"]
  node_operations["Operations view<br/>[Operations.jsx]"]
  node_agent_graph["Agent activity graph<br/>[AgentGraph.jsx]"]
  node_events["Events and trace<br/>[Events.jsx]"]
  node_incidents["Incident workflow<br/>[Incidents.jsx]"]
  node_policy_view["Policy view<br/>[PolicyPage.jsx]"]
  node_ghost_view["Ghost sessions<br/>[GhostShell.jsx]"]
  node_api_client["Console API client<br/>[lib.js]"]
end

node_user(("User"))
node_agent(("Agent or tool"))

node_user -->|"requests action"| node_agent
node_agent -->|"submits action"| node_sdk
node_agent -->|"uses proxy"| node_mcp
node_sdk -->|"sends request"| node_gateway_server
node_mcp -.->|"proxies actions"| node_gateway_server
node_gateway_server -.->|"routes requests"| node_engine
node_engine -.->|"checks policy"| node_guards
node_engine -->|"requests scores"| node_semantic
node_engine -->|"requests detection"| node_pii
node_pii -->|"detects spans"| node_ner_model
node_ner_model -->|"uses rules"| node_pii_rules
node_engine -.->|"runs permitted action"| node_execution
node_execution -.->|"returns result"| node_engine
node_engine -.->|"isolates untrusted code"| node_ghost
node_engine -->|"requests explanation"| node_explain
node_engine -.->|"loads policy"| node_policy
node_engine -.->|"records decisions"| node_store
node_store -->|"appends audit entry"| node_audit_chain
node_engine -.->|"reports timings"| node_telemetry
node_dashboard -->|"uses API client"| node_api_client
node_dashboard -->|"renders view"| node_operations
node_dashboard -->|"renders view"| node_agent_graph
node_dashboard -->|"renders view"| node_events
node_dashboard -->|"renders view"| node_incidents
node_dashboard -->|"renders view"| node_policy_view
node_dashboard -->|"renders view"| node_ghost_view
node_api_client -->|"calls API"| node_gateway_server
node_agent_graph -->|"loads audit stream"| node_api_client
node_operations -.->|"shows runtime metrics"| node_api_client
node_events -.->|"shows audit events"| node_api_client
node_incidents -.->|"manages incidents"| node_api_client
node_policy_view -.->|"reads policy"| node_api_client
node_ghost_view -.->|"shows recordings"| node_api_client

click node_sdk "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/sdk/python/masqe_sdk.py"
click node_mcp "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/sdk/python/masqe_mcp.py"
click node_gateway_server "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/server.go"
click node_engine "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/engine.go"
click node_execution "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/execution.go"
click node_guards "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/guards.go"
click node_semantic "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/ai-guard/server.py"
click node_pii "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/ai-guard/ner_service.py"
click node_ner_model "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/ai-guard/masqe_engine/ner.py"
click node_pii_rules "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/ai-guard/masqe_engine/rules.py"
click node_explain "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/ai-guard/explain.py"
click node_ghost "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/ai-guard/ghost.py"
click node_policy "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/config.go"
click node_store "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/store.go"
click node_audit_chain "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/audit_chain.go"
click node_telemetry "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/telemetry.go"
click node_dashboard "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/App.jsx"
click node_operations "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/pages/Operations.jsx"
click node_agent_graph "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/pages/AgentGraph.jsx"
click node_events "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/pages/Events.jsx"
click node_incidents "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/pages/Incidents.jsx"
click node_policy_view "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/pages/PolicyPage.jsx"
click node_ghost_view "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/GhostShell.jsx"
click node_api_client "https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/lib.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk,node_mcp,node_user toneBlue
class node_gateway_server,node_engine,node_execution,node_guards toneAmber
class node_semantic,node_pii,node_ner_model,node_pii_rules,node_explain,node_ghost toneMint
class node_policy,node_store,node_audit_chain,node_telemetry toneRose
class node_dashboard,node_operations,node_agent_graph,node_events,node_incidents,node_policy_view,node_ghost_view,node_api_client,node_agent toneIndigo
```

## Components

### Client integrations

- [Python SDK](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/sdk/python/masqe_sdk.py): `sdk/python/masqe_sdk.py`
- [MCP proxy](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/sdk/python/masqe_mcp.py): `sdk/python/masqe_mcp.py`

### Go security gateway

- [HTTP gateway](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/server.go): `gateway/server.go`
- [Decision engine](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/engine.go): `gateway/engine.go`
- [Action execution](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/execution.go): `gateway/execution.go`
- [Deterministic guards](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/guards.go): `gateway/guards.go`

### Python guard services

- [Semantic scoring](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/ai-guard/server.py): `ai-guard/server.py`
- [PII detection](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/ai-guard/ner_service.py): `ai-guard/ner_service.py`
- [NER engine](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/ai-guard/masqe_engine/ner.py): `ai-guard/masqe_engine/ner.py`
- [PII rules and spans](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/ai-guard/masqe_engine/rules.py): `ai-guard/masqe_engine/rules.py`
- [Decision explanations](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/ai-guard/explain.py): `ai-guard/explain.py`
- [Ghost Shell](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/ai-guard/ghost.py): `ai-guard/ghost.py`

### Audit and policy state

- [Policy and threat feed](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/config.go): `gateway/config.go`
- [Audit store](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/store.go): `gateway/store.go`
- [Tamper-evident chain](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/audit_chain.go): `gateway/audit_chain.go`
- [Telemetry and traces](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/gateway/telemetry.go): `gateway/telemetry.go`

### Security console

- [Console application](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/App.jsx): `dashboard/src/App.jsx`
- [Operations view](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/pages/Operations.jsx): `dashboard/src/pages/Operations.jsx`
- [Agent activity graph](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/pages/AgentGraph.jsx): `dashboard/src/pages/AgentGraph.jsx`
- [Events and trace](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/pages/Events.jsx): `dashboard/src/pages/Events.jsx`
- [Incident workflow](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/pages/Incidents.jsx): `dashboard/src/pages/Incidents.jsx`
- [Policy view](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/pages/PolicyPage.jsx): `dashboard/src/pages/PolicyPage.jsx`
- [Ghost sessions](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/GhostShell.jsx): `dashboard/src/GhostShell.jsx`
- [Console API client](https://github.com/oskarbartoszyk/masqe-hackyeah2026/blob/main/dashboard/src/lib.js): `dashboard/src/lib.js`

### Other components

- **User**
- **Agent or tool**

## Connections

- User → Agent or tool: requests action (evidence: `README.md`)
- Agent or tool → Python SDK: submits action (evidence: `sdk/python/masqe_sdk.py`)
- Agent or tool → MCP proxy: uses proxy (evidence: `README.md`)
- Python SDK → HTTP gateway: sends request (evidence: `sdk/python/masqe_sdk.py`)
- MCP proxy → HTTP gateway: proxies actions (evidence: `README.md`)
- HTTP gateway → Decision engine: routes requests (evidence: `README.md`)
- Decision engine → Deterministic guards: checks policy (evidence: `README.md`)
- Decision engine → Semantic scoring: requests scores (evidence: `README.md`)
- Decision engine → PII detection: requests detection (evidence: `README.md`)
- PII detection → NER engine: detects spans (evidence: `ai-guard/ner_service.py`)
- NER engine → PII rules and spans: uses rules (evidence: `ai-guard/masqe_engine/ner.py`)
- Decision engine → Action execution: runs permitted action (evidence: `README.md`)
- Action execution → Decision engine: returns result (evidence: `README.md`)
- Decision engine → Ghost Shell: isolates untrusted code (evidence: `README.md`)
- Decision engine → Decision explanations: requests explanation (evidence: `README.md`)
- Decision engine → Policy and threat feed: loads policy (evidence: `README.md`)
- Decision engine → Audit store: records decisions (evidence: `README.md`)
- Audit store → Tamper-evident chain: appends audit entry (evidence: `README.md`)
- Decision engine → Telemetry and traces: reports timings (evidence: `README.md`)
- Console application → Console API client: uses API client (evidence: `dashboard/src/App.jsx`)
- Console application → Operations view: renders view (evidence: `dashboard/src/App.jsx`)
- Console application → Agent activity graph: renders view (evidence: `dashboard/src/App.jsx`)
- Console application → Events and trace: renders view (evidence: `dashboard/src/App.jsx`)
- Console application → Incident workflow: renders view (evidence: `dashboard/src/App.jsx`)
- Console application → Policy view: renders view (evidence: `dashboard/src/App.jsx`)
- Console application → Ghost sessions: renders view (evidence: `dashboard/src/App.jsx`)
- Console API client → HTTP gateway: calls API (evidence: `dashboard/src/lib.js`)
- Agent activity graph → Console API client: loads audit stream (evidence: `dashboard/src/pages/AgentGraph.jsx`)
- Operations view → Console API client: shows runtime metrics (evidence: `README.md`)
- Events and trace → Console API client: shows audit events (evidence: `README.md`)
- Incident workflow → Console API client: manages incidents (evidence: `README.md`)
- Policy view → Console API client: reads policy (evidence: `README.md`)
- Ghost sessions → Console API client: shows recordings (evidence: `README.md`)
