How 1samay/codeguard-os- works
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: engine.py Scan engine · main.py API app · scan_runner.py Scan runner · upload.py Upload router
Components 26
Runtime surfaces
User-facing UI, local API, and desktop packaging
- Desktop shell · Optional local app wrapper around the web UI and API
desktop/backend_entry.py - Main process · Starts the packaged desktop application
desktop/src/main.js - Preload bridge · Safe bridge between desktop shell and renderer
desktop/src/preload.js - API app · Creates the local FastAPI control plane
apps/api/main.py - Upload router · Accepts projects and starts local scans
apps/api/routers/upload.py - Scans router · Exposes scan history and scan status endpoints
apps/api/routers/scans.py - Reports router · Serves generated report artifacts and download links
apps/api/routers/reports.py - Web app · Local dashboard for uploads, scans, and reports
apps/web/pages/index.tsx - API client · Frontend boundary to the backend API
apps/web/lib/api.ts
Analysis engine
Scanner core and rule packs
- Scan engine · Coordinates file reading, detection, scanners, and scoring
packages/scanner_core/engine.py - File reader · Loads source files for analysis
packages/scanner_core/file_reader.py - Language detect · Infers languages and framework hints from source trees
packages/scanner_core/lang_detector.py - Rule loader · Loads analysis rules from JSON packs
packages/scanner_core/rule_loader.py - Secret scanner · Finds exposed secrets and credentials
packages/scanner_core/scanners/secret_scanner.py - Backend scanner · Checks server-side code patterns and risks
packages/scanner_core/scanners/backend_scanner.py - API scanner · Analyzes API-specific code and boundary issues
packages/scanner_core/scanners/api_scanner.py - Dependency scan · Flags dependency-related risks from project manifests
packages/scanner_core/scanners/dependency_scanner.py - Scoring · Ranks findings and computes severity or score output
packages/scanner_core/score_engine.py
Local state
SQLite metadata, uploads, and generated reports
- Schema · Defines local persistence tables for scans and reports
apps/api/db/schema.sql - Repositories · Reads and writes scan history and metadata in SQLite
apps/api/db/repositories.py - Extractor · Safely unpacks uploaded archives and guards the filesystem boundary
apps/api/services/extractor.py - Scan runner · Runs the scanner engine and persists results locally
apps/api/services/scan_runner.py - Report builder · Generates HTML and PDF reports on disk
apps/api/services/report_builder.py - Uploads · Stored ZIPs and extracted project trees
uploads/.gitkeep - Reports · Generated HTML and PDF report artifacts
reports/.gitkeep
Shared contract
Models shared across API and scanner layers
- Shared models · Common issue, score, and report shapes used across layers
packages/shared/models.py
Connections 28
- 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