# digiator42/gritshield architecture

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

- Interactive diagram: https://gitdiagram.com/digiator42/gritshield
- Repository: https://github.com/digiator42/gritshield

## Overview

GritShield is an async-first Rust web framework. Its main workflow is an application defining routes and handlers, the router dispatching incoming HTTP requests through middleware to handlers, and handlers returning HTTP responses. The framework also provides persistence, security, dependency injection, admin and OpenAPI tooling, and an MCP server. The graph includes documented capabilities whose implementation was not sampled; their internal wiring is left out where evidence is unavailable.

Main entry points: [`src/routing/engine/router.rs`](https://github.com/digiator42/gritshield/blob/main/src/routing/engine/router.rs) (Router and dispatch), [`src/middleware/auth.rs`](https://github.com/digiator42/gritshield/blob/main/src/middleware/auth.rs) (Request middleware), [`src/mcp/engine.rs`](https://github.com/digiator42/gritshield/blob/main/src/mcp/engine.rs) (MCP protocol engine), [`src/routing/engine/handler.rs`](https://github.com/digiator42/gritshield/blob/main/src/routing/engine/handler.rs) (Route handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["HTTP Runtime"]
  node_server["HTTP server<br/>[server.rs]"]
  node_router["Router and dispatch<br/>[router.rs]"]
  node_request["Request parsing<br/>[request.rs]"]
  node_handler["Route handlers<br/>[handler.rs]"]
  node_response["HTTP responses<br/>[response.rs]"]
end

subgraph group_security["Security"]
  node_middleware["Request middleware<br/>[auth.rs]"]
  node_sessions["Sessions and JWT<br/>[session.rs]"]
  node_xss["XSS sanitizer<br/>[xss.rs]"]
  node_access["RBAC and rate limits"]
end

subgraph group_data["Data and Admin"]
  node_database[("Database connection<br/>[db.rs]")]
  node_repositories["Repositories and JQL"]
  node_admin["Admin panel"]
  node_admin_auth["Admin authentication<br/>[handlers.rs]"]
end

subgraph group_platform["Framework Services"]
  node_core["DI, events, jobs"]
  node_templates_ws["Templates and WebSockets<br/>[templates.rs]"]
end

subgraph group_integrations["Developer Integrations"]
  node_macros["Compile-time macros"]
  node_swagger["OpenAPI and Swagger<br/>[spec.rs]"]
  node_mcp["MCP protocol engine<br/>[engine.rs]"]
  node_mcp_transports["MCP transports<br/>[transport.rs]"]
end

node_developer(("Application developer"))
node_browser(("Browser client"))

node_browser -->|"sends HTTP"| node_server
node_server -.->|"serves routes"| node_router
node_router -->|"runs middleware"| node_middleware
node_router -->|"initializes services"| node_core
node_request -->|"uses sanitizer"| node_xss
node_handler -->|"converts results"| node_response
node_handler -->|"trusts safe output"| node_xss
node_middleware -->|"checks sessions and JWT"| node_sessions
node_middleware -->|"parses CSRF form"| node_request
node_admin_auth -->|"uses sessions"| node_sessions
node_admin -->|"searches records"| node_repositories
node_repositories -.->|"queries database"| node_database
node_developer -->|"declares routes"| node_macros
node_router -.->|"registers documentation routes"| node_swagger
node_router -.->|"registers MCP routes"| node_mcp
node_mcp -.->|"serves via transports"| node_mcp_transports
node_developer -->|"annotates repositories"| node_admin
node_developer -->|"documents schemas"| node_swagger
node_developer -->|"declares tools and resources"| node_mcp
node_router -.->|"serves templates and WebSockets"| node_templates_ws
node_router -.->|"enforces access controls"| node_access

click node_server "https://github.com/digiator42/gritshield/blob/main/src/http/server.rs"
click node_router "https://github.com/digiator42/gritshield/blob/main/src/routing/engine/router.rs"
click node_request "https://github.com/digiator42/gritshield/blob/main/src/http/request.rs"
click node_handler "https://github.com/digiator42/gritshield/blob/main/src/routing/engine/handler.rs"
click node_response "https://github.com/digiator42/gritshield/blob/main/src/http/response.rs"
click node_middleware "https://github.com/digiator42/gritshield/blob/main/src/middleware/auth.rs"
click node_sessions "https://github.com/digiator42/gritshield/blob/main/src/security/session.rs"
click node_xss "https://github.com/digiator42/gritshield/blob/main/src/security/xss.rs"
click node_access "https://github.com/digiator42/gritshield/tree/main/src/security"
click node_database "https://github.com/digiator42/gritshield/blob/main/src/database/db.rs"
click node_repositories "https://github.com/digiator42/gritshield/tree/main/src/database/repository"
click node_admin "https://github.com/digiator42/gritshield/tree/main/src/gritadmin/dashboard"
click node_admin_auth "https://github.com/digiator42/gritshield/blob/main/src/gritadmin/auth/handlers.rs"
click node_core "https://github.com/digiator42/gritshield/tree/main/src/core"
click node_templates_ws "https://github.com/digiator42/gritshield/blob/main/src/routing/templates.rs"
click node_macros "https://github.com/digiator42/gritshield/tree/main/src/gritshield_macros/src"
click node_swagger "https://github.com/digiator42/gritshield/blob/main/src/core/swagger/spec.rs"
click node_mcp "https://github.com/digiator42/gritshield/blob/main/src/mcp/engine.rs"
click node_mcp_transports "https://github.com/digiator42/gritshield/blob/main/src/mcp/transport.rs"

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_server,node_router,node_request,node_handler,node_response,node_browser toneBlue
class node_middleware,node_sessions,node_xss,node_access toneAmber
class node_database,node_repositories,node_admin,node_admin_auth toneMint
class node_core,node_templates_ws toneRose
class node_macros,node_swagger,node_mcp,node_mcp_transports,node_developer toneIndigo
```

## Components

### HTTP Runtime

- [HTTP server](https://github.com/digiator42/gritshield/blob/main/src/http/server.rs): `src/http/server.rs`
- [Router and dispatch](https://github.com/digiator42/gritshield/blob/main/src/routing/engine/router.rs): `src/routing/engine/router.rs`
- [Request parsing](https://github.com/digiator42/gritshield/blob/main/src/http/request.rs): `src/http/request.rs`
- [Route handlers](https://github.com/digiator42/gritshield/blob/main/src/routing/engine/handler.rs): `src/routing/engine/handler.rs`
- [HTTP responses](https://github.com/digiator42/gritshield/blob/main/src/http/response.rs): `src/http/response.rs`

### Security

- [Request middleware](https://github.com/digiator42/gritshield/blob/main/src/middleware/auth.rs): `src/middleware/auth.rs`
- [Sessions and JWT](https://github.com/digiator42/gritshield/blob/main/src/security/session.rs): `src/security/session.rs`
- [XSS sanitizer](https://github.com/digiator42/gritshield/blob/main/src/security/xss.rs): `src/security/xss.rs`
- [RBAC and rate limits](https://github.com/digiator42/gritshield/tree/main/src/security): `src/security`

### Data and Admin

- [Database connection](https://github.com/digiator42/gritshield/blob/main/src/database/db.rs): `src/database/db.rs`
- [Repositories and JQL](https://github.com/digiator42/gritshield/tree/main/src/database/repository): `src/database/repository`
- [Admin panel](https://github.com/digiator42/gritshield/tree/main/src/gritadmin/dashboard): `src/gritadmin/dashboard`
- [Admin authentication](https://github.com/digiator42/gritshield/blob/main/src/gritadmin/auth/handlers.rs): `src/gritadmin/auth/handlers.rs`

### Framework Services

- [DI, events, jobs](https://github.com/digiator42/gritshield/tree/main/src/core): `src/core`
- [Templates and WebSockets](https://github.com/digiator42/gritshield/blob/main/src/routing/templates.rs): `src/routing/templates.rs`

### Developer Integrations

- [Compile-time macros](https://github.com/digiator42/gritshield/tree/main/src/gritshield_macros/src): `src/gritshield_macros/src`
- [OpenAPI and Swagger](https://github.com/digiator42/gritshield/blob/main/src/core/swagger/spec.rs): `src/core/swagger/spec.rs`
- [MCP protocol engine](https://github.com/digiator42/gritshield/blob/main/src/mcp/engine.rs): `src/mcp/engine.rs`
- [MCP transports](https://github.com/digiator42/gritshield/blob/main/src/mcp/transport.rs): `src/mcp/transport.rs`

### Other components

- **Application developer**
- **Browser client**

## Connections

- Browser client → HTTP server: sends HTTP
- HTTP server → Router and dispatch: serves routes
- Router and dispatch → Request middleware: runs middleware (evidence: `src/routing/engine/router.rs`)
- Router and dispatch → DI, events, jobs: initializes services (evidence: `src/routing/engine/router.rs`)
- Request parsing → XSS sanitizer: uses sanitizer (evidence: `src/http/request.rs`)
- Route handlers → HTTP responses: converts results (evidence: `src/routing/engine/handler.rs`)
- Route handlers → XSS sanitizer: trusts safe output (evidence: `src/routing/engine/handler.rs`)
- Request middleware → Sessions and JWT: checks sessions and JWT (evidence: `src/middleware/auth.rs`)
- Request middleware → Request parsing: parses CSRF form (evidence: `src/middleware/auth.rs`)
- Admin authentication → Sessions and JWT: uses sessions (evidence: `src/gritadmin/auth/handlers.rs`)
- Admin panel → Repositories and JQL: searches records (evidence: `src/gritadmin/dashboard/handlers/search.rs`)
- Repositories and JQL → Database connection: queries database
- Application developer → Compile-time macros: declares routes
- Router and dispatch → OpenAPI and Swagger: registers documentation routes
- Router and dispatch → MCP protocol engine: registers MCP routes
- MCP protocol engine → MCP transports: serves via transports
- Application developer → Admin panel: annotates repositories
- Application developer → OpenAPI and Swagger: documents schemas
- Application developer → MCP protocol engine: declares tools and resources
- Router and dispatch → Templates and WebSockets: serves templates and WebSockets
- Router and dispatch → RBAC and rate limits: enforces access controls (evidence: `src/routing/engine/router.rs`)