adammostofi/codesentinel

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.