# kreativepardha/major-sast-agent architecture

> Architecture diagram of the GitHub repository kreativepardha/major-sast-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kreativepardha/major-sast-agent
- Repository: https://github.com/kreativepardha/major-sast-agent

## Overview

1. **Repository shape**
   - This is a two-app monorepo: a **React/Vite frontend** and a **Node/Express backend**.
   - The backend is where the SAST workflow, persistence, queueing, authentication, and AI enrichment live; the frontend is a thin dashboard/client for those APIs.

2. **Frontend boundary**
   - The frontend is a single-page app built with **TypeScript, React, Tailwind, and shadcn/ui**.
   - Main surfaces are organized into pages for **login, dashboard, new scan, scan history, and scan results**.
   - `MainLayout`, `Sidebar`, and `Topbar` define the application shell, while `authStore` and `lib/api.ts` handle client-side auth state and backend communication.
   - The UI is geared toward operational monitoring: dashboard summaries, scan progress/results, and severity breakdowns.

3. **Backend entry and cross-cutting concerns**
   - `src/index.ts` is the backend composition root.
   - Cross-cutting middleware includes **request logging**, **rate limiting**, **authentication guarding**, and a centralized **error handler**.
   - `passport.ts` indicates Passport-based auth integration, and the backend is structured to protect private routes rather than exposing everything anonymously.

4. **API module boundaries**
   - The backend is split into four domain modules:
     - **auth**: user/session/login flow
     - **projects**: project registration and management
     - **scans**: scan creation, status, history, and result retrieval
     - **issues**: vulnerability findings surfaced from scans
   - Each module follows a standard controller/routes/service split, which makes the HTTP layer, business logic, and resource wiring easy to separate in a diagram.

5. **Persistence layer**
   - Persistence uses **Prisma ORM** against **PostgreSQL**.
   - `prisma/schema.prisma` and the migrations define the application data model and evolution path.
   - The core persistent entities are implied by the modules: **users/auth state, projects, scans, and issues**.
   - This is the authoritative store for scan history and vulnerability findings, not just a cache.

6. **Asynchronous scan pipeline**
   - Scan execution is not treated as a synchronous request/response operation.
   - `src/queue/scan.queue.ts` shows a **BullMQ-style queue** backed by **Redis**, which decouples scan submission from scan processing.
   - This is a key architectural boundary: the user starts a scan, the backend enqueues work, and processing happens asynchronously so the UI can stay responsive.

7. **SAST engine integration**
   - The scanner subsystem in `src/scanner` is the bridge to the static-analysis engine.
   - `bearer.service.ts` and `parser.ts` indicate integration with **Bearer CLI** output and post-processing of raw scan results into normalized findings.
   - `ai-scanner.service.ts` suggests a second stage that enriches or explains findings after the raw SAST pass.
   - In diagrams, this is the external analysis boundary between the application and the code-scanning toolchain.

8. **AI provider abstraction**
   - The AI layer is intentionally abstracted through `ai.interface.ts` plus provider implementations for **Gemini**, **OpenAI**, and **NVIDIA**.
   - The README says Gemini is primary with OpenAI as fallback, so the architecture includes **provider failover** rather than a single hard dependency.
   - This layer is used to explain vulnerabilities, summarize them, and likely produce remediation guidance from the raw scan output.

9. **Scan data flow**
   - Typical flow: a user logs in, creates or selects a project, submits a scan, the backend persists the scan record, and the job is pushed to the queue.
   - The scanner then runs Bearer, parses findings, applies AI enrichment, and writes issues/results back through Prisma.
   - Final scan state and findings are served back through the scans/issues APIs for the history and results pages.

10. **Real-time feedback**
   - The README calls out **SSE**, which means scan progress is streamed from backend to frontend as the job advances.
   - This is important architecturally because the UI does not have to poll for every phase; it can render phase-by-phase updates and completion status in near real time.

11. **External dependencies and infrastructure**
   - The runtime stack depends on **PostgreSQL**, **Redis**, external **LLM APIs** (Gemini/OpenAI), and the **Bearer CLI** toolchain.
   - The environment also implies an external **OAuth provider** via Passport configuration, likely for GitHub login based on the README.
   - `docker-compose.yml` and the two Dockerfiles show the system is containerized for local and production-like deployment.

12. **What to show in an architecture diagram**
   - Draw the frontend as a consumer of the backend API and SSE stream.
   - Draw the backend as four logical domains: auth, projects, scans, issues.
   - Place Prisma/Postgres as the system of record, Redis/BullMQ as the async work queue, Bearer CLI as the scanning engine, and Gemini/OpenAI as the AI enrichment layer.
   - Emphasize the asynchronous scan pipeline and the provider-abstraction/fallback behavior, since those are the most important architectural differentiators in this repo.

Main entry points: [`backend/src/index.ts`](https://github.com/kreativepardha/major-sast-agent/blob/main/backend/src/index.ts) (API entry), [`backend/prisma/schema.prisma`](https://github.com/kreativepardha/major-sast-agent/blob/main/backend/prisma/schema.prisma) (Prisma layer), [`frontend/src/pages`](https://github.com/kreativepardha/major-sast-agent/tree/main/frontend/src/pages) (Pages), [`backend/src/modules/auth`](https://github.com/kreativepardha/major-sast-agent/tree/main/backend/src/modules/auth) (Auth module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>React SPA<br/>[App.tsx]"]
  node_frontend_layout["Layout<br/>UI shell<br/>[MainLayout.tsx]"]
  node_frontend_pages["Pages<br/>Views"]
  node_frontend_store_api["Auth + API<br/>Client state<br/>[authStore.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_entry["API entry<br/>Express root<br/>[index.ts]"]
  node_backend_middleware["Middleware<br/>Cross-cutting"]
  node_backend_auth["Auth module"]
  node_backend_projects["Projects module"]
  node_backend_scans["Scans module"]
  node_backend_issues["Issues module"]
  node_backend_queue["Scan queue<br/>Async job queue<br/>[scan.queue.ts]"]
  node_backend_scanner["Scanner bridge<br/>SAST integration"]
  node_backend_ai["AI providers<br/>Provider layer<br/>[ai.interface.ts]"]
  node_backend_db[("Prisma layer<br/>ORM<br/>[schema.prisma]")]
end

subgraph group_external["External systems"]
  node_external_postgres[("PostgreSQL<br/>Database")]
  node_external_redis[("Redis<br/>Broker")]
  node_external_bearer{{"Bearer CLI<br/>Scanner"}}
  node_external_llms{{"LLM APIs<br/>Gemini/OpenAI/NVIDIA"}}
  node_external_oauth{{"OAuth provider<br/>Passport auth"}}
end

node_frontend_app -->|"renders"| node_frontend_layout
node_frontend_layout -->|"hosts"| node_frontend_pages
node_frontend_pages -->|"reads/writes"| node_frontend_store_api
node_frontend_store_api -->|"calls API"| node_backend_entry
node_frontend_pages -->|"SSE/status"| node_backend_entry
node_backend_entry -->|"applies"| node_backend_middleware
node_backend_entry -->|"routes"| node_backend_auth
node_backend_entry -->|"routes"| node_backend_projects
node_backend_entry -->|"routes"| node_backend_scans
node_backend_entry -->|"routes"| node_backend_issues
node_backend_auth -->|"delegates"| node_external_oauth
node_backend_scans -->|"enqueues"| node_backend_queue
node_backend_queue -->|"backed by"| node_external_redis
node_backend_queue -->|"runs job"| node_backend_scanner
node_backend_scanner -->|"invokes"| node_external_bearer
node_backend_scanner -->|"enriches via"| node_backend_ai
node_backend_ai -->|"calls"| node_external_llms
node_backend_scans -->|"persists"| node_backend_db
node_backend_issues -->|"reads/writes"| node_backend_db
node_backend_projects -->|"persists"| node_backend_db
node_backend_auth -->|"persists"| node_backend_db
node_backend_db -->|"connects to"| node_external_postgres

click node_frontend_app "https://github.com/kreativepardha/major-sast-agent/blob/main/frontend/src/App.tsx"
click node_frontend_layout "https://github.com/kreativepardha/major-sast-agent/blob/main/frontend/src/components/layout/MainLayout.tsx"
click node_frontend_pages "https://github.com/kreativepardha/major-sast-agent/tree/main/frontend/src/pages"
click node_frontend_store_api "https://github.com/kreativepardha/major-sast-agent/blob/main/frontend/src/store/authStore.ts"
click node_backend_entry "https://github.com/kreativepardha/major-sast-agent/blob/main/backend/src/index.ts"
click node_backend_middleware "https://github.com/kreativepardha/major-sast-agent/tree/main/backend/src/middleware"
click node_backend_auth "https://github.com/kreativepardha/major-sast-agent/tree/main/backend/src/modules/auth"
click node_backend_projects "https://github.com/kreativepardha/major-sast-agent/tree/main/backend/src/modules/projects"
click node_backend_scans "https://github.com/kreativepardha/major-sast-agent/tree/main/backend/src/modules/scans"
click node_backend_issues "https://github.com/kreativepardha/major-sast-agent/tree/main/backend/src/modules/issues"
click node_backend_queue "https://github.com/kreativepardha/major-sast-agent/blob/main/backend/src/queue/scan.queue.ts"
click node_backend_scanner "https://github.com/kreativepardha/major-sast-agent/tree/main/backend/src/scanner"
click node_backend_ai "https://github.com/kreativepardha/major-sast-agent/blob/main/backend/src/modules/ai/ai.interface.ts"
click node_backend_db "https://github.com/kreativepardha/major-sast-agent/blob/main/backend/prisma/schema.prisma"

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_frontend_app,node_frontend_layout,node_frontend_pages,node_frontend_store_api toneBlue
class node_backend_entry,node_backend_middleware,node_backend_auth,node_backend_projects,node_backend_scans,node_backend_issues,node_backend_queue,node_backend_scanner,node_backend_ai,node_backend_db toneAmber
class node_external_postgres,node_external_redis,node_external_bearer,node_external_llms,node_external_oauth toneMint
```

## Components

### Frontend

React/Vite SPA for auth, scan monitoring, and results.

- [App shell](https://github.com/kreativepardha/major-sast-agent/blob/main/frontend/src/App.tsx): React SPA · Main client application entry and routing. · `frontend/src/App.tsx`
- [Layout](https://github.com/kreativepardha/major-sast-agent/blob/main/frontend/src/components/layout/MainLayout.tsx): UI shell · Main layout, sidebar, and top bar framing the dashboard. · `frontend/src/components/layout/MainLayout.tsx`
- [Pages](https://github.com/kreativepardha/major-sast-agent/tree/main/frontend/src/pages): Views · Login, dashboard, new scan, history, and results screens. · `frontend/src/pages`
- [Auth + API](https://github.com/kreativepardha/major-sast-agent/blob/main/frontend/src/store/authStore.ts): Client state · Client auth store and backend API client used by the UI. · `frontend/src/store/authStore.ts`

### Backend

Express API, async scan pipeline, persistence, and AI enrichment.

- [API entry](https://github.com/kreativepardha/major-sast-agent/blob/main/backend/src/index.ts): Express root · Backend composition root that wires middleware and routes. · `backend/src/index.ts`
- [Middleware](https://github.com/kreativepardha/major-sast-agent/tree/main/backend/src/middleware): Cross-cutting · Request logging, rate limiting, auth guarding, and error handling. · `backend/src/middleware`
- [Auth module](https://github.com/kreativepardha/major-sast-agent/tree/main/backend/src/modules/auth): Module · Login and session flow exposed through controllers, routes, and service. · `backend/src/modules/auth`
- [Projects module](https://github.com/kreativepardha/major-sast-agent/tree/main/backend/src/modules/projects): Module · Project registration and management endpoints. · `backend/src/modules/projects`
- [Scans module](https://github.com/kreativepardha/major-sast-agent/tree/main/backend/src/modules/scans): Module · Scan submission, status, history, and result retrieval. · `backend/src/modules/scans`
- [Issues module](https://github.com/kreativepardha/major-sast-agent/tree/main/backend/src/modules/issues): Module · Vulnerability findings surfaced from scan output. · `backend/src/modules/issues`
- [Scan queue](https://github.com/kreativepardha/major-sast-agent/blob/main/backend/src/queue/scan.queue.ts): Async job queue · BullMQ-style queue that decouples scan requests from processing. · `backend/src/queue/scan.queue.ts`
- [Scanner bridge](https://github.com/kreativepardha/major-sast-agent/tree/main/backend/src/scanner): SAST integration · Bearer execution, parsing, and AI-assisted scan processing. · `backend/src/scanner`
- [AI providers](https://github.com/kreativepardha/major-sast-agent/blob/main/backend/src/modules/ai/ai.interface.ts): Provider layer · Abstracted Gemini, OpenAI, and NVIDIA providers with fallback behavior. · `backend/src/modules/ai/ai.interface.ts`
- [Prisma layer](https://github.com/kreativepardha/major-sast-agent/blob/main/backend/prisma/schema.prisma): ORM · Prisma schema and data access for persisted users, projects, scans, and issues. · `backend/prisma/schema.prisma`

### External systems

Datastores, queue broker, scanner toolchain, and LLM providers.

- **PostgreSQL**: Database · System of record for auth state, scans, and findings.
- **Redis**: Broker · Queue backend for asynchronous scan execution.
- **Bearer CLI**: Scanner · Static-analysis engine used to generate raw scan findings.
- **LLM APIs**: Gemini/OpenAI/NVIDIA · External model providers used to explain and summarize findings.
- **OAuth provider**: Passport auth · External identity provider used through Passport integration.

## Connections

- App shell → Layout: renders · The SPA uses the main application shell for navigation and framing.
- Layout → Pages: hosts · Layout presents the operational pages inside a shared shell.
- Pages → Auth + API: reads/writes · Pages use client auth state and API calls for backend interaction.
- Auth + API → API entry: calls API · Client communicates with backend HTTP endpoints.
- Pages → API entry: SSE/status · Scan pages consume near real-time progress updates from the backend.
- API entry → Middleware: applies · Incoming requests pass through cross-cutting middleware.
- API entry → Auth module: routes · Auth endpoints are mounted from the auth module.
- API entry → Projects module: routes · Project endpoints are mounted from the projects module.
- API entry → Scans module: routes · Scan lifecycle endpoints are mounted from the scans module.
- API entry → Issues module: routes · Issue retrieval endpoints are mounted from the issues module.
- Auth module → OAuth provider: delegates · Passport-based login integrates with an external identity provider.
- Scans module → Scan queue: enqueues · Scan creation persists state then pushes asynchronous work to the queue.
- Scan queue → Redis: backed by · The queue uses Redis for durable job buffering.
- Scan queue → Scanner bridge: runs job · Queued work executes the scan pipeline.
- Scanner bridge → Bearer CLI: invokes · Scanner bridge runs Bearer CLI to obtain raw findings.
- Scanner bridge → AI providers: enriches via · Raw results are passed through the AI abstraction for explanation and remediation guidance.
- AI providers → LLM APIs: calls · Provider layer talks to Gemini, OpenAI, or NVIDIA models with fallback.
- Scans module → Prisma layer: persists · Scan records and state transitions are stored via Prisma.
- Issues module → Prisma layer: reads/writes · Findings are stored and served from the database.
- Projects module → Prisma layer: persists · Project records are managed through Prisma.
- Auth module → Prisma layer: persists · User/session auth data is stored in the database.
- Prisma layer → PostgreSQL: connects to · Prisma uses PostgreSQL as the system of record.
