# 1samay/codeguard-os- architecture

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

- Interactive diagram: https://gitdiagram.com/1samay/codeguard-os-
- Repository: https://github.com/1samay/codeguard-os-

## Overview

1. **What this repo is**
   - CodeGuard OS is a **local-first offline security scanner**. The core architecture is built around a **FastAPI backend**, a **Next.js frontend**, and a **Python scanner engine** that all run on the user’s machine.
   - The main architectural constraint is that **project source code stays on disk locally**; there is no cloud processing or hosted database.

2. **Primary runtime surfaces**
   - **`apps/web`** is the user-facing UI for uploads, scan history, scan detail, and report viewing.
   - **`apps/api`** is the local control plane: it accepts uploads, starts scans, stores metadata, and serves report/download endpoints.
   - **`packages/scanner_core`** contains the actual analysis engine and rule-based scanners.
   - **`desktop/`** appears to package the local stack into a desktop app shell, likely wrapping the same backend/UI for distribution.

3. **Frontend boundary**
   - The web app is a **Next.js + TypeScript** client with pages for dashboard, upload, scans, and report detail.
   - UI components like issue lists, score cards, severity badges, and file trees indicate the frontend is mostly a **viewer/orchestrator**, not the analyzer.
   - `apps/web/lib/api.ts` is the integration boundary to the backend API.

4. **Backend API boundary**
   - The FastAPI service is organized into routers for **health, upload, scans, and reports**.
   - `apps/api/main.py` is the app entrypoint; `logging_config.py` and `config.py` manage runtime behavior.
   - The API is not just a thin CRUD layer: the readme shows that **upload triggers a full synchronous scan** in the local MVP.

5. **Local persistence model**
   - Scan history is stored in **SQLite** under `data/codeguard.db`.
   - `apps/api/db/schema.sql`, `database.py`, and `repositories.py` define the database boundary and data access layer.
   - The database appears to hold at least **projects, scans, issues, scores, and report metadata**; this is the source of truth for scan status and history.

6. **Filesystem as an architectural subsystem**
   - The product is heavily filesystem-centered:
     - uploaded ZIPs land in `uploads/{project_id}/`
     - extracted source lands in `uploads/{project_id}/extracted/`
     - generated artifacts land in `reports/`
   - These directories are part of the durable local state, alongside SQLite in `data/`.
   - Scan deletion cleans up both database rows and on-disk artifacts, so the filesystem is a first-class backend concern.

7. **Ingestion and extraction flow**
   - The upload route accepts a ZIP, stores it locally, then performs **safe extraction** with protections against path traversal, symlinks, executable files, and oversized extraction patterns.
   - The system also counts files/lines and builds a readable file tree after extraction.
   - This ingestion pipeline is a clear boundary: untrusted user input enters here, and the system sanitizes it before analysis.

8. **Scanner engine architecture**
   - `packages/scanner_core/engine.py` orchestrates analysis.
   - Supporting modules provide:
     - file reading
     - language/framework detection
     - rule loading
     - scoring
   - The engine then invokes multiple specialized scanners and deduplicates findings before results are persisted.

9. **Analysis modules and rule sources**
   - The scanner set is split by concern:
     - `secret_scanner`
     - `backend_scanner`
     - `api_scanner`
     - `dependency_scanner`
   - Rule data lives in `packages/rules/*.json`, so at least part of the analysis is **data-driven** rather than hardcoded.
   - Findings include file/line context and severity, which is important for the frontend’s issue rendering and report generation.

10. **Shared model boundary**
   - `packages/shared/models.py` holds shared Python models used across API and scanner layers.
   - This is the contract boundary between scanning output, API responses, and stored records.
   - It helps keep the backend and scanner engine aligned on issue, score, and report structures.

11. **Reporting subsystem**
   - `apps/api/services/report_builder.py` generates offline **HTML and PDF reports** from scan results.
   - Reports are written locally under `reports/` and are downloadable through dedicated API endpoints.
   - The HTML report is the richer artifact; the PDF is a readable summary.

12. **Operational entry points**
   - `apps/api/cli.py` provides maintenance and developer commands for:
     - database initialization
     - file tree generation
     - language detection
     - direct local scanning
   - This means the scanner can run both as an **HTTP service** and as a **CLI tool**, which is useful for offline workflows and debugging.

13. **Desktop packaging layer**
   - The `desktop/` folder suggests an Electron-style shell around the local system.
   - `backend_entry.py`, `src/main.js`, and `src/preload.js` imply the desktop app likely starts or embeds the backend and presents the web UI in a packaged local application.
   - For an architecture diagram, this should be shown as an **optional packaging layer**, not the primary analysis engine.

14. **End-to-end data flow**
   - The main flow is: **upload ZIP / local project → safe extraction → file tree + language detection → scanner engine → issue/score persistence in SQLite → report generation → UI display/download**.
   - The key architectural boundaries are **frontend vs backend**, **backend vs scanner core**, and **runtime state vs local disk/SQLite storage**.
   - No external SaaS dependencies are part of the core v0.1 architecture.

Main entry points: [`packages/scanner_core/engine.py`](https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/engine.py) (Scan engine), [`apps/api/main.py`](https://github.com/1samay/codeguard-os-/blob/main/apps/api/main.py) (API app), [`apps/api/services/scan_runner.py`](https://github.com/1samay/codeguard-os-/blob/main/apps/api/services/scan_runner.py) (Scan runner), [`apps/api/routers/upload.py`](https://github.com/1samay/codeguard-os-/blob/main/apps/api/routers/upload.py) (Upload router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime surfaces"]
  node_desktop_shell["Desktop shell<br/>packaging<br/>[backend_entry.py]"]
  node_desktop_main["Main process<br/>electron entry<br/>[main.js]"]
  node_desktop_bridge["Preload bridge<br/>electron preload<br/>[preload.js]"]
  node_api_app["API app<br/>fastapi entry<br/>[main.py]"]
  node_api_upload["Upload router<br/>route boundary<br/>[upload.py]"]
  node_api_scans["Scans router<br/>route boundary<br/>[scans.py]"]
  node_api_reports["Reports router<br/>route boundary<br/>[reports.py]"]
  node_web_ui["Web app<br/>nextjs frontend<br/>[index.tsx]"]
  node_web_api["API client<br/>frontend integration<br/>[api.ts]"]
end

subgraph group_analysis["Analysis engine"]
  node_scanner_engine["Scan engine<br/>analysis orchestrator<br/>[engine.py]"]
  node_file_reader["File reader<br/>io helper<br/>[file_reader.py]"]
  node_lang_detector["Language detect<br/>classifier<br/>[lang_detector.py]"]
  node_rule_loader["Rule loader<br/>rules source<br/>[rule_loader.py]"]
  node_secret_scanner["Secret scanner<br/>[secret_scanner.py]"]
  node_backend_scanner["Backend scanner<br/>[backend_scanner.py]"]
  node_api_scanner["API scanner<br/>[api_scanner.py]"]
  node_dependency_scanner["Dependency scan<br/>scanner"]
  node_score_engine["Scoring<br/>ranking<br/>[score_engine.py]"]
end

subgraph group_state["Local state"]
  node_db_schema["Schema<br/>[schema.sql]"]
  node_db_repo["Repositories<br/>data access<br/>[repositories.py]"]
  node_extractor["Extractor<br/>ingestion service<br/>[extractor.py]"]
  node_scan_runner["Scan runner<br/>orchestration service<br/>[scan_runner.py]"]
  node_report_builder["Report builder<br/>report service<br/>[report_builder.py]"]
  node_uploads_store["Uploads<br/>filesystem store<br/>[.gitkeep]"]
  node_reports_store["Reports<br/>filesystem store<br/>[.gitkeep]"]
end

subgraph group_shared["Shared contract"]
  node_shared_models["Shared models<br/>contract models<br/>[models.py]"]
end

node_desktop_shell -->|"launches"| node_desktop_main
node_desktop_main -->|"loads"| node_desktop_bridge
node_desktop_shell -->|"hosts"| node_web_ui
node_web_ui -->|"calls"| node_web_api
node_api_app -->|"mounts"| node_api_upload
node_api_app -->|"mounts"| node_api_scans
node_api_app -->|"mounts"| node_api_reports
node_api_upload -->|"uses"| node_extractor
node_api_upload -->|"starts"| node_scan_runner
node_scan_runner -->|"invokes"| node_scanner_engine
node_scanner_engine -->|"reads"| node_file_reader
node_scanner_engine -->|"detects"| node_lang_detector
node_scanner_engine -->|"loads"| node_rule_loader
node_scanner_engine -->|"runs"| node_secret_scanner
node_scanner_engine -->|"runs"| node_backend_scanner
node_scanner_engine -->|"runs"| node_api_scanner
node_scanner_engine -->|"runs"| node_dependency_scanner
node_scanner_engine -->|"scores"| node_score_engine
node_scanner_engine -->|"emits"| node_shared_models
node_scan_runner -->|"persists"| node_db_repo
node_db_repo -->|"implements"| node_db_schema
node_extractor -->|"writes"| node_uploads_store
node_scan_runner -->|"analyzes"| node_uploads_store
node_report_builder -->|"writes"| node_reports_store
node_api_reports -->|"uses"| node_report_builder
node_web_ui -->|"renders"| node_shared_models
node_api_app -->|"queries"| node_db_repo
node_api_app -->|"orchestrates"| node_scan_runner

click node_desktop_shell "https://github.com/1samay/codeguard-os-/blob/main/desktop/backend_entry.py"
click node_desktop_main "https://github.com/1samay/codeguard-os-/blob/main/desktop/src/main.js"
click node_desktop_bridge "https://github.com/1samay/codeguard-os-/blob/main/desktop/src/preload.js"
click node_api_app "https://github.com/1samay/codeguard-os-/blob/main/apps/api/main.py"
click node_api_upload "https://github.com/1samay/codeguard-os-/blob/main/apps/api/routers/upload.py"
click node_api_scans "https://github.com/1samay/codeguard-os-/blob/main/apps/api/routers/scans.py"
click node_api_reports "https://github.com/1samay/codeguard-os-/blob/main/apps/api/routers/reports.py"
click node_web_ui "https://github.com/1samay/codeguard-os-/blob/main/apps/web/pages/index.tsx"
click node_web_api "https://github.com/1samay/codeguard-os-/blob/main/apps/web/lib/api.ts"
click node_scanner_engine "https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/engine.py"
click node_file_reader "https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/file_reader.py"
click node_lang_detector "https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/lang_detector.py"
click node_rule_loader "https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/rule_loader.py"
click node_secret_scanner "https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/scanners/secret_scanner.py"
click node_backend_scanner "https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/scanners/backend_scanner.py"
click node_api_scanner "https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/scanners/api_scanner.py"
click node_dependency_scanner "https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/scanners/dependency_scanner.py"
click node_score_engine "https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/score_engine.py"
click node_shared_models "https://github.com/1samay/codeguard-os-/blob/main/packages/shared/models.py"
click node_db_schema "https://github.com/1samay/codeguard-os-/blob/main/apps/api/db/schema.sql"
click node_db_repo "https://github.com/1samay/codeguard-os-/blob/main/apps/api/db/repositories.py"
click node_extractor "https://github.com/1samay/codeguard-os-/blob/main/apps/api/services/extractor.py"
click node_scan_runner "https://github.com/1samay/codeguard-os-/blob/main/apps/api/services/scan_runner.py"
click node_report_builder "https://github.com/1samay/codeguard-os-/blob/main/apps/api/services/report_builder.py"
click node_uploads_store "https://github.com/1samay/codeguard-os-/blob/main/uploads/.gitkeep"
click node_reports_store "https://github.com/1samay/codeguard-os-/blob/main/reports/.gitkeep"

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_desktop_shell,node_desktop_main,node_desktop_bridge,node_api_app,node_api_upload,node_api_scans,node_api_reports,node_web_ui,node_web_api toneBlue
class node_scanner_engine,node_file_reader,node_lang_detector,node_rule_loader,node_secret_scanner,node_backend_scanner,node_api_scanner,node_dependency_scanner,node_score_engine toneAmber
class node_db_schema,node_db_repo,node_extractor,node_scan_runner,node_report_builder,node_uploads_store,node_reports_store toneMint
class node_shared_models toneRose
```

## Components

### Runtime surfaces

User-facing UI, local API, and desktop packaging

- [Desktop shell](https://github.com/1samay/codeguard-os-/blob/main/desktop/backend_entry.py): packaging · Optional local app wrapper around the web UI and API · `desktop/backend_entry.py`
- [Main process](https://github.com/1samay/codeguard-os-/blob/main/desktop/src/main.js): electron entry · Starts the packaged desktop application · `desktop/src/main.js`
- [Preload bridge](https://github.com/1samay/codeguard-os-/blob/main/desktop/src/preload.js): electron preload · Safe bridge between desktop shell and renderer · `desktop/src/preload.js`
- [API app](https://github.com/1samay/codeguard-os-/blob/main/apps/api/main.py): fastapi entry · Creates the local FastAPI control plane · `apps/api/main.py`
- [Upload router](https://github.com/1samay/codeguard-os-/blob/main/apps/api/routers/upload.py): route boundary · Accepts projects and starts local scans · `apps/api/routers/upload.py`
- [Scans router](https://github.com/1samay/codeguard-os-/blob/main/apps/api/routers/scans.py): route boundary · Exposes scan history and scan status endpoints · `apps/api/routers/scans.py`
- [Reports router](https://github.com/1samay/codeguard-os-/blob/main/apps/api/routers/reports.py): route boundary · Serves generated report artifacts and download links · `apps/api/routers/reports.py`
- [Web app](https://github.com/1samay/codeguard-os-/blob/main/apps/web/pages/index.tsx): nextjs frontend · Local dashboard for uploads, scans, and reports · `apps/web/pages/index.tsx`
- [API client](https://github.com/1samay/codeguard-os-/blob/main/apps/web/lib/api.ts): frontend integration · Frontend boundary to the backend API · `apps/web/lib/api.ts`

### Analysis engine

Scanner core and rule packs

- [Scan engine](https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/engine.py): analysis orchestrator · Coordinates file reading, detection, scanners, and scoring · `packages/scanner_core/engine.py`
- [File reader](https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/file_reader.py): io helper · Loads source files for analysis · `packages/scanner_core/file_reader.py`
- [Language detect](https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/lang_detector.py): classifier · Infers languages and framework hints from source trees · `packages/scanner_core/lang_detector.py`
- [Rule loader](https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/rule_loader.py): rules source · Loads analysis rules from JSON packs · `packages/scanner_core/rule_loader.py`
- [Secret scanner](https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/scanners/secret_scanner.py): scanner · Finds exposed secrets and credentials · `packages/scanner_core/scanners/secret_scanner.py`
- [Backend scanner](https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/scanners/backend_scanner.py): scanner · Checks server-side code patterns and risks · `packages/scanner_core/scanners/backend_scanner.py`
- [API scanner](https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/scanners/api_scanner.py): scanner · Analyzes API-specific code and boundary issues · `packages/scanner_core/scanners/api_scanner.py`
- [Dependency scan](https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/scanners/dependency_scanner.py): scanner · Flags dependency-related risks from project manifests · `packages/scanner_core/scanners/dependency_scanner.py`
- [Scoring](https://github.com/1samay/codeguard-os-/blob/main/packages/scanner_core/score_engine.py): ranking · Ranks findings and computes severity or score output · `packages/scanner_core/score_engine.py`

### Local state

SQLite metadata, uploads, and generated reports

- [Schema](https://github.com/1samay/codeguard-os-/blob/main/apps/api/db/schema.sql): sqlite schema · Defines local persistence tables for scans and reports · `apps/api/db/schema.sql`
- [Repositories](https://github.com/1samay/codeguard-os-/blob/main/apps/api/db/repositories.py): data access · Reads and writes scan history and metadata in SQLite · `apps/api/db/repositories.py`
- [Extractor](https://github.com/1samay/codeguard-os-/blob/main/apps/api/services/extractor.py): ingestion service · Safely unpacks uploaded archives and guards the filesystem boundary · `apps/api/services/extractor.py`
- [Scan runner](https://github.com/1samay/codeguard-os-/blob/main/apps/api/services/scan_runner.py): orchestration service · Runs the scanner engine and persists results locally · `apps/api/services/scan_runner.py`
- [Report builder](https://github.com/1samay/codeguard-os-/blob/main/apps/api/services/report_builder.py): report service · Generates HTML and PDF reports on disk · `apps/api/services/report_builder.py`
- [Uploads](https://github.com/1samay/codeguard-os-/blob/main/uploads/.gitkeep): filesystem store · Stored ZIPs and extracted project trees · `uploads/.gitkeep`
- [Reports](https://github.com/1samay/codeguard-os-/blob/main/reports/.gitkeep): filesystem store · Generated HTML and PDF report artifacts · `reports/.gitkeep`

### Shared contract

Models shared across API and scanner layers

- [Shared models](https://github.com/1samay/codeguard-os-/blob/main/packages/shared/models.py): contract models · Common issue, score, and report shapes used across layers · `packages/shared/models.py`

## Connections

- Desktop shell → Main process: launches · Desktop package starts the Electron main process
- Main process → Preload bridge: loads · Main process exposes the preload bridge to the renderer
- Desktop shell → Web app: hosts · Desktop wrapper presents the Next.js UI locally
- Web app → API client: calls · UI interacts with the backend through the API client
- API app → Upload router: mounts · FastAPI app registers upload routes
- API app → Scans router: mounts · FastAPI app registers scan routes
- API app → Reports router: mounts · FastAPI app registers report routes
- Upload router → Extractor: uses · Upload handling delegates archive extraction and safety checks
- Upload router → Scan runner: starts · Uploading a project triggers a local scan
- Scan runner → Scan engine: invokes · Runner executes the core analysis pipeline
- Scan engine → File reader: reads · Engine loads project source files
- Scan engine → Language detect: detects · Engine infers languages and frameworks
- Scan engine → Rule loader: loads · Engine pulls rule packs from JSON data
- Scan engine → Secret scanner: runs · Engine executes secret detection
- Scan engine → Backend scanner: runs · Engine executes backend analysis
- Scan engine → API scanner: runs · Engine executes API analysis
- Scan engine → Dependency scan: runs · Engine executes dependency analysis
- Scan engine → Scoring: scores · Engine normalizes and ranks findings
- Scan engine → Shared models: emits · Engine produces shared issue and score structures
- Scan runner → Repositories: persists · Runner stores scan outcomes and metadata
- Repositories → Schema: implements · Repository follows the schema definition
- Extractor → Uploads: writes · Uploaded archives and extracted sources stay on disk
- Scan runner → Uploads: analyzes · Runner scans the extracted project tree in place
- Report builder → Reports: writes · Reports are generated as local artifacts
- Reports router → Report builder: uses · Report endpoints read from the report builder output
- Web app → Shared models: renders · Frontend displays issues, scores, and report data
- API app → Repositories: queries · API serves scan history and detail views from SQLite
- API app → Scan runner: orchestrates · API coordinates scan execution in the local MVP
