# ns-matrix/codeguard-ai architecture

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

- Interactive diagram: https://gitdiagram.com/ns-matrix/codeguard-ai
- Repository: https://github.com/ns-matrix/codeguard-ai

## Overview

CodeGuard AI is a browser-based code validation and review platform. A user submits code from the Validator page; the frontend store calls the REST API, where the validation service combines language detection, deterministic syntax/security checks, and local Ollama analysis, then persists results for history and reporting. The UI also exposes focused AI actions, formatting, model/settings controls, history, and dashboard analytics. The README documents the overall REST and storage integrations; edges into unsampled implementation details are limited to relationships shown by the source index or README.

Main entry points: [`backend/app/main.py`](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/main.py) (FastAPI app), [`backend/app/services/validation_service.py`](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/services/validation_service.py) (Validation orchestrator), [`backend/app/db/database.py`](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/db/database.py) (Database access), [`frontend/src/App.tsx`](https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/App.tsx) (App routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser application"]
  node_app["App routing<br/>[App.tsx]"]
  node_validator["Validator page<br/>[Validator.tsx]"]
  node_panel["Action results"]
  node_store["Validation state<br/>[validationStore.ts]"]
  node_api_client["REST client<br/>[api.ts]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_history_ui["History views<br/>[History.tsx]"]
  node_settings["Settings page<br/>[Settings.tsx]"]
end

subgraph group_api["Backend API"]
  node_main["FastAPI app<br/>[main.py]"]
  node_validation_api["Validation routes<br/>[validation.py]"]
  node_models_api["Model routes<br/>[models.py]"]
  node_project_api["Project routes<br/>[projects.py]"]
  node_history_api["History routes<br/>[history.py]"]
  node_stats_api["Statistics routes<br/>[stats.py]"]
end

subgraph group_engine["Validation engine"]
  node_orchestrator["Validation orchestrator"]
  node_language["Language detector"]
  node_syntax["Syntax validator"]
  node_security["Security scanner"]
  node_formatter["Code formatter<br/>[formatter.py]"]
  node_ollama_service["LLM service<br/>[ollama_service.py]"]
end

subgraph group_data["Persistence and integrations"]
  node_db[("Database access<br/>[database.py]")]
  node_records["Validation records<br/>[validation.py]"]
  node_postgres[("PostgreSQL / Supabase")]
  node_ollama["Ollama server"]
end

node_user(("Developer"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_validator
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_history_ui
node_app -->|"routes to"| node_settings
node_validator -->|"renders"| node_panel
node_validator -->|"dispatches"| node_store
node_panel -->|"dispatches"| node_store
node_store -->|"calls"| node_api_client
node_api_client -->|"REST requests"| node_main
node_dashboard -->|"loads analytics"| node_api_client
node_history_ui -.->|"loads history"| node_api_client
node_settings -->|"reads and updates"| node_store
node_main -->|"registers"| node_validation_api
node_main -->|"registers"| node_models_api
node_main -->|"registers"| node_project_api
node_main -->|"registers"| node_history_api
node_main -->|"registers"| node_stats_api
node_validation_api -->|"invokes"| node_orchestrator
node_orchestrator -->|"detects language"| node_language
node_orchestrator -->|"checks syntax"| node_syntax
node_orchestrator -->|"scans security"| node_security
node_orchestrator -->|"requests analysis"| node_ollama_service
node_orchestrator -->|"formats code"| node_formatter
node_orchestrator -->|"creates records"| node_records
node_validation_api -->|"gets session"| node_db
node_history_api -->|"queries"| node_db
node_stats_api -->|"queries"| node_db
node_project_api -->|"uses session"| node_db
node_models_api -->|"lists models"| node_ollama_service
node_db -->|"reads and writes"| node_postgres
node_ollama_service -->|"HTTP analysis"| node_ollama
node_main -->|"initializes"| node_db
node_main -->|"checks connection"| node_ollama_service

click node_app "https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/App.tsx"
click node_validator "https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/pages/Validator.tsx"
click node_panel "https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/components/ValidationPanel/ValidationPanel.tsx"
click node_store "https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/stores/validationStore.ts"
click node_api_client "https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/services/api.ts"
click node_dashboard "https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/pages/Dashboard.tsx"
click node_history_ui "https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/pages/History.tsx"
click node_settings "https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/pages/Settings.tsx"
click node_main "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/main.py"
click node_validation_api "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/api/validation.py"
click node_models_api "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/api/models.py"
click node_project_api "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/api/projects.py"
click node_history_api "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/api/history.py"
click node_stats_api "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/api/stats.py"
click node_orchestrator "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/services/validation_service.py"
click node_language "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/services/language_detector.py"
click node_syntax "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/services/syntax_validator.py"
click node_security "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/services/security_scanner.py"
click node_formatter "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/services/formatter.py"
click node_ollama_service "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/services/ollama_service.py"
click node_db "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/db/database.py"
click node_records "https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/models/validation.py"

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_app,node_validator,node_panel,node_store,node_api_client,node_dashboard,node_history_ui,node_settings toneBlue
class node_main,node_validation_api,node_models_api,node_project_api,node_history_api,node_stats_api toneAmber
class node_orchestrator,node_language,node_syntax,node_security,node_formatter,node_ollama_service toneMint
class node_db,node_records,node_postgres,node_ollama toneRose
class node_user toneIndigo
```

## Components

### Browser application

- [App routing](https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Validator page](https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/pages/Validator.tsx): `frontend/src/pages/Validator.tsx`
- [Action results](https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/components/ValidationPanel/ValidationPanel.tsx): `frontend/src/components/ValidationPanel/ValidationPanel.tsx`
- [Validation state](https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/stores/validationStore.ts): `frontend/src/stores/validationStore.ts`
- [REST client](https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Dashboard](https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [History views](https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/pages/History.tsx): `frontend/src/pages/History.tsx`
- [Settings page](https://github.com/ns-matrix/codeguard-ai/blob/master/frontend/src/pages/Settings.tsx): `frontend/src/pages/Settings.tsx`

### Backend API

- [FastAPI app](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/main.py): `backend/app/main.py`
- [Validation routes](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/api/validation.py): `backend/app/api/validation.py`
- [Model routes](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/api/models.py): `backend/app/api/models.py`
- [Project routes](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/api/projects.py): `backend/app/api/projects.py`
- [History routes](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/api/history.py): `backend/app/api/history.py`
- [Statistics routes](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/api/stats.py): `backend/app/api/stats.py`

### Validation engine

- [Validation orchestrator](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/services/validation_service.py): `backend/app/services/validation_service.py`
- [Language detector](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/services/language_detector.py): `backend/app/services/language_detector.py`
- [Syntax validator](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/services/syntax_validator.py): `backend/app/services/syntax_validator.py`
- [Security scanner](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/services/security_scanner.py): `backend/app/services/security_scanner.py`
- [Code formatter](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/services/formatter.py): `backend/app/services/formatter.py`
- [LLM service](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/services/ollama_service.py): `backend/app/services/ollama_service.py`

### Persistence and integrations

- [Database access](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/db/database.py): `backend/app/db/database.py`
- [Validation records](https://github.com/ns-matrix/codeguard-ai/blob/master/backend/app/models/validation.py): `backend/app/models/validation.py`
- **PostgreSQL / Supabase**
- **Ollama server**

### Other components

- **Developer**

## Connections

- Developer → App routing: uses (evidence: `README.md`)
- App routing → Validator page: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Dashboard: routes to (evidence: `frontend/src/App.tsx`)
- App routing → History views: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Settings page: routes to (evidence: `frontend/src/App.tsx`)
- Validator page → Action results: renders (evidence: `frontend/src/pages/Validator.tsx`)
- Validator page → Validation state: dispatches (evidence: `frontend/src/pages/Validator.tsx`)
- Action results → Validation state: dispatches (evidence: `frontend/src/components/ValidationPanel/ValidationPanel.tsx`)
- Validation state → REST client: calls (evidence: `frontend/src/stores/validationStore.ts`)
- REST client → FastAPI app: REST requests (evidence: `README.md`)
- Dashboard → REST client: loads analytics (evidence: `frontend/src/pages/Dashboard.tsx`)
- History views → REST client: loads history
- Settings page → Validation state: reads and updates (evidence: `frontend/src/pages/Settings.tsx`)
- FastAPI app → Validation routes: registers (evidence: `backend/app/main.py`)
- FastAPI app → Model routes: registers (evidence: `backend/app/main.py`)
- FastAPI app → Project routes: registers (evidence: `backend/app/main.py`)
- FastAPI app → History routes: registers (evidence: `backend/app/main.py`)
- FastAPI app → Statistics routes: registers (evidence: `backend/app/main.py`)
- Validation routes → Validation orchestrator: invokes (evidence: `backend/app/api/validation.py`)
- Validation orchestrator → Language detector: detects language (evidence: `backend/app/services/validation_service.py`)
- Validation orchestrator → Syntax validator: checks syntax (evidence: `backend/app/services/validation_service.py`)
- Validation orchestrator → Security scanner: scans security (evidence: `backend/app/services/validation_service.py`)
- Validation orchestrator → LLM service: requests analysis (evidence: `backend/app/services/validation_service.py`)
- Validation orchestrator → Code formatter: formats code (evidence: `backend/app/services/validation_service.py`)
- Validation orchestrator → Validation records: creates records (evidence: `backend/app/services/validation_service.py`)
- Validation routes → Database access: gets session (evidence: `backend/app/api/validation.py`)
- History routes → Database access: queries (evidence: `backend/app/api/history.py`)
- Statistics routes → Database access: queries (evidence: `backend/app/api/stats.py`)
- Project routes → Database access: uses session (evidence: `backend/app/api/projects.py`)
- Model routes → LLM service: lists models (evidence: `backend/app/api/models.py`)
- Database access → PostgreSQL / Supabase: reads and writes (evidence: `README.md`)
- LLM service → Ollama server: HTTP analysis (evidence: `backend/app/services/ollama_service.py`)
- FastAPI app → Database access: initializes (evidence: `backend/app/main.py`)
- FastAPI app → LLM service: checks connection (evidence: `backend/app/main.py`)
