# adammostofi/codesentinel architecture

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

- Interactive diagram: https://gitdiagram.com/adammostofi/codesentinel
- Repository: https://github.com/adammostofi/codesentinel

## Overview

1. **Overall shape**  
   CodeSentinel is a two-service application: a **Next.js frontend** for user interaction and a **FastAPI backend** for scan execution, result storage, and remediation generation. The main architectural boundary is HTTP between the browser and backend API.

2. **Frontend subsystem**  
   The frontend lives under `frontend/src/app` and is a small App Router application. `page.jsx` is the main user-facing screen, `layout.jsx` sets the shell, and `globals.css` provides global styling. `src/lib/api.js` is the client-side boundary to the backend, so the UI does not contain scanning logic itself.

3. **Backend application entry and configuration**  
   `backend/app/main.py` is the FastAPI entrypoint. Runtime configuration is centralized in `backend/app/core/config.py`, with environment variables supplied through `.env` files and Docker Compose. This makes the backend behavior configurable without changing the frontend.

4. **API layer**  
   `backend/app/api/routes.py` defines the public REST contract: upload a ZIP for scanning, list past scans, fetch one scan in detail, delete scans, and perform health checks. This layer is the orchestration layer; it coordinates services rather than doing heavy processing itself.

5. **Scan ingestion and file handling**  
   `backend/app/services/file_handler.py` is the boundary for ZIP upload handling. It is responsible for receiving user-submitted archives, likely validating them, unpacking them, and preparing a project workspace for analysis. This separates untrusted file input from the scanning logic.

6. **Security analysis engine**  
   `backend/app/services/scanner.py` is the core analysis subsystem. The README indicates it combines **Bandit**, **Safety**, and **Semgrep**, so the scanner aggregates findings from multiple security tools into one normalized result set. This is the primary computation path of the backend.

7. **AI remediation subsystem**  
   `backend/app/services/llm.py` integrates with **Groq** for remediation guidance. This is optional and environment-driven: if an API key is present, findings can be enriched with human-readable fixes and vulnerable-vs-fixed code comparisons. The LLM is an enhancement layer on top of deterministic scanner output, not the source of truth for detection.

8. **Persistence and scan history**  
   `backend/app/models/scan.py` and `backend/app/database.py` define the SQLAlchemy-backed persistence layer, using **SQLite** for local storage. Scan metadata, status, risk score, and vulnerability details are persisted so the frontend can render history and drill-down views without re-running scans.

9. **End-to-end data flow**  
   The typical flow is: user uploads a ZIP in the frontend → frontend calls the backend `/api/scan` endpoint → backend extracts and scans the project → results are scored, optionally enriched with AI remediation, and saved to SQLite → frontend reads `/api/scans` or `/api/scan/{scan_id}` to present summaries and detailed findings. Delete operations also flow back to the backend to remove stored scan data and associated artifacts.

10. **Runtime and deployment boundary**  
    The project is containerized with **Docker Compose**, with separate Dockerfiles for backend and frontend. The default runtime exposes the frontend on port 3000 and the backend on port 8000. This deployment model keeps the browser UI, API server, and scanner dependencies isolated while making local setup reproducible.

11. **Operational characteristics**  
    The backend depends on Python 3.12+ and security-tooling packages, so scan execution is server-side and not performed in the browser. The frontend is a lightweight presentation layer with real-time progress and history views, while the backend owns all stateful and compute-heavy work.

12. **What to draw in an architecture diagram**  
    The most important boxes are: **browser UI**, **Next.js app**, **FastAPI API**, **scan/file services**, **security tools (Bandit/Safety/Semgrep)**, **Groq LLM**, and **SQLite database**. The key arrows are upload request, scan execution, result persistence, history retrieval, and optional remediation enrichment.

Main entry points: [`backend/app/api/routes.py`](https://github.com/adammostofi/codesentinel/blob/master/backend/app/api/routes.py) (REST routes), [`frontend/src/app`](https://github.com/adammostofi/codesentinel/tree/master/frontend/src/app) (Next app), [`docker-compose.yml`](https://github.com/adammostofi/codesentinel/blob/master/docker-compose.yml) (Docker Compose), [`backend/app/services/scanner.py`](https://github.com/adammostofi/codesentinel/blob/master/backend/app/services/scanner.py) (Scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser(("Browser UI<br/>user client"))
  node_fe_app["Next app<br/>Next.js app"]
  node_fe_page["Main page<br/>UI page<br/>[page.jsx]"]
  node_fe_layout["Shell layout<br/>UI layout<br/>[layout.jsx]"]
  node_fe_css["Global styles<br/>[globals.css]"]
  node_fe_api["API client<br/>HTTP client<br/>[api.js]"]
end

subgraph group_backend["Backend"]
  node_api_main["FastAPI app<br/>API entrypoint<br/>[main.py]"]
  node_api_routes["REST routes<br/>HTTP API<br/>[routes.py]"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_file_handler["File handler<br/>upload service<br/>[file_handler.py]"]
  node_scanner["Scanner<br/>analysis engine<br/>[scanner.py]"]
  node_llm["Remediation AI<br/>llm integration<br/>[llm.py]"]
  node_model_scan["Scan model<br/>orm model<br/>[scan.py]"]
  node_database[("SQLite DB<br/>persistence<br/>[database.py]")]
end

subgraph group_infra["Runtime"]
  node_docker["Docker Compose<br/>deployment<br/>[docker-compose.yml]"]
  node_fe_docker["Frontend image<br/>container build"]
  node_be_docker["Backend image<br/>container build"]
  node_env["Env files<br/>runtime config<br/>[.env.example]"]
end

node_browser -->|"uses"| node_fe_app
node_fe_app -->|"renders"| node_fe_page
node_fe_app -->|"wraps"| node_fe_layout
node_fe_app -->|"styles"| node_fe_css
node_fe_page -->|"calls"| node_fe_api
node_fe_api -->|"HTTP"| node_api_routes
node_api_main -->|"mounts"| node_api_routes
node_api_main -->|"loads"| node_config
node_api_routes -->|"delegates"| node_file_handler
node_api_routes -->|"delegates"| node_scanner
node_api_routes -.->|"enriches"| node_llm
node_api_routes -->|"persists"| node_model_scan
node_model_scan -->|"stored in"| node_database
node_scanner -.->|"optionally uses"| node_llm
node_scanner -->|"writes results"| node_database
node_docker -->|"builds"| node_fe_docker
node_docker -->|"builds"| node_be_docker
node_docker -->|"configures"| node_env
node_config -->|"reads"| node_env

click node_fe_app "https://github.com/adammostofi/codesentinel/tree/master/frontend/src/app"
click node_fe_page "https://github.com/adammostofi/codesentinel/blob/master/frontend/src/app/page.jsx"
click node_fe_layout "https://github.com/adammostofi/codesentinel/blob/master/frontend/src/app/layout.jsx"
click node_fe_css "https://github.com/adammostofi/codesentinel/blob/master/frontend/src/app/globals.css"
click node_fe_api "https://github.com/adammostofi/codesentinel/blob/master/frontend/src/lib/api.js"
click node_api_main "https://github.com/adammostofi/codesentinel/blob/master/backend/app/main.py"
click node_api_routes "https://github.com/adammostofi/codesentinel/blob/master/backend/app/api/routes.py"
click node_config "https://github.com/adammostofi/codesentinel/blob/master/backend/app/core/config.py"
click node_file_handler "https://github.com/adammostofi/codesentinel/blob/master/backend/app/services/file_handler.py"
click node_scanner "https://github.com/adammostofi/codesentinel/blob/master/backend/app/services/scanner.py"
click node_llm "https://github.com/adammostofi/codesentinel/blob/master/backend/app/services/llm.py"
click node_model_scan "https://github.com/adammostofi/codesentinel/blob/master/backend/app/models/scan.py"
click node_database "https://github.com/adammostofi/codesentinel/blob/master/backend/app/database.py"
click node_docker "https://github.com/adammostofi/codesentinel/blob/master/docker-compose.yml"
click node_fe_docker "https://github.com/adammostofi/codesentinel/tree/master/frontend/Dockerfile"
click node_be_docker "https://github.com/adammostofi/codesentinel/tree/master/backend/Dockerfile"
click node_env "https://github.com/adammostofi/codesentinel/blob/master/.env.example"

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_browser,node_fe_app,node_fe_page,node_fe_layout,node_fe_css,node_fe_api toneBlue
class node_api_main,node_api_routes,node_config,node_file_handler,node_scanner,node_llm,node_model_scan,node_database toneAmber
class node_docker,node_fe_docker,node_be_docker,node_env toneMint
```

## Components

### Frontend

Next.js browser-facing application

- **Browser UI**: user client · User interacts with the application in the browser
- [Next app](https://github.com/adammostofi/codesentinel/tree/master/frontend/src/app): Next.js app · App Router frontend shell and pages · `frontend/src/app`
- [Main page](https://github.com/adammostofi/codesentinel/blob/master/frontend/src/app/page.jsx): UI page · Primary scan and history screen · `frontend/src/app/page.jsx`
- [Shell layout](https://github.com/adammostofi/codesentinel/blob/master/frontend/src/app/layout.jsx): UI layout · Shared application layout and chrome · `frontend/src/app/layout.jsx`
- [Global styles](https://github.com/adammostofi/codesentinel/blob/master/frontend/src/app/globals.css): styles · Application-wide styling · `frontend/src/app/globals.css`
- [API client](https://github.com/adammostofi/codesentinel/blob/master/frontend/src/lib/api.js): HTTP client · Frontend boundary for backend requests · `frontend/src/lib/api.js`

### Backend

FastAPI service for scans and storage

- [FastAPI app](https://github.com/adammostofi/codesentinel/blob/master/backend/app/main.py): API entrypoint · Backend application startup and wiring · `backend/app/main.py`
- [REST routes](https://github.com/adammostofi/codesentinel/blob/master/backend/app/api/routes.py): HTTP API · Public scan, history, delete, and health endpoints · `backend/app/api/routes.py`
- [Config](https://github.com/adammostofi/codesentinel/blob/master/backend/app/core/config.py): settings · Backend runtime configuration and environment settings · `backend/app/core/config.py`
- [File handler](https://github.com/adammostofi/codesentinel/blob/master/backend/app/services/file_handler.py): upload service · Receives and prepares uploaded ZIP archives · `backend/app/services/file_handler.py`
- [Scanner](https://github.com/adammostofi/codesentinel/blob/master/backend/app/services/scanner.py): analysis engine · Aggregates security findings from Bandit, Safety, and Semgrep · `backend/app/services/scanner.py`
- [Remediation AI](https://github.com/adammostofi/codesentinel/blob/master/backend/app/services/llm.py): llm integration · Optional Groq-powered remediation guidance · `backend/app/services/llm.py`
- [Scan model](https://github.com/adammostofi/codesentinel/blob/master/backend/app/models/scan.py): orm model · Persisted scan metadata and vulnerability details · `backend/app/models/scan.py`
- [SQLite DB](https://github.com/adammostofi/codesentinel/blob/master/backend/app/database.py): persistence · SQLAlchemy-backed local storage for scan history · `backend/app/database.py`

### Runtime

Containerization and environment setup

- [Docker Compose](https://github.com/adammostofi/codesentinel/blob/master/docker-compose.yml): deployment · Local multi-service runtime and environment wiring · `docker-compose.yml`
- [Frontend image](https://github.com/adammostofi/codesentinel/tree/master/frontend/Dockerfile): container build · Container definition for the Next.js frontend · `frontend/Dockerfile`
- [Backend image](https://github.com/adammostofi/codesentinel/tree/master/backend/Dockerfile): container build · Container definition for the FastAPI backend · `backend/Dockerfile`
- [Env files](https://github.com/adammostofi/codesentinel/blob/master/.env.example): runtime config · Example environment settings for both services · `.env.example`

## Connections

- Browser UI → Next app: uses · Browser loads the frontend application
- Next app → Main page: renders · Main page provides the primary user workflow
- Next app → Shell layout: wraps · Layout defines the shared shell
- Next app → Global styles: styles · Global CSS applies to the app
- Main page → API client: calls · UI submits scans and fetches history through the client boundary
- API client → REST routes: HTTP · Frontend communicates with the backend REST API
- FastAPI app → REST routes: mounts · FastAPI entrypoint registers the route layer
- FastAPI app → Config: loads · Application startup reads runtime settings
- REST routes → File handler: delegates · Upload endpoints hand off archive preparation
- REST routes → Scanner: delegates · Scan endpoints invoke the analysis engine
- REST routes → Remediation AI: enriches · Optional remediation enrichment is attached to findings
- REST routes → Scan model: persists · Route layer stores and reads scan records
- Scan model → SQLite DB: stored in · ORM model is backed by SQLite persistence
- Scanner → Remediation AI: optionally uses · Remediation generation can augment deterministic findings
- Scanner → SQLite DB: writes results · Scan outputs are saved for later retrieval
- Docker Compose → Frontend image: builds · Compose includes the frontend container image
- Docker Compose → Backend image: builds · Compose includes the backend container image
- Docker Compose → Env files: configures · Deployment uses environment-based settings
- Config → Env files: reads · Backend settings are supplied via environment values