How kreativepardha/major-sast-agent works
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: index.ts API entry · schema.prisma Prisma layer · pages Pages · auth Auth module
Components 19
Frontend
React/Vite SPA for auth, scan monitoring, and results.
- App shell · Main client application entry and routing.
frontend/src/App.tsx - Layout · Main layout, sidebar, and top bar framing the dashboard.
frontend/src/components/layout/MainLayout.tsx - Pages · Login, dashboard, new scan, history, and results screens.
frontend/src/pages - Auth + API · 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 · Backend composition root that wires middleware and routes.
backend/src/index.ts - Middleware · Request logging, rate limiting, auth guarding, and error handling.
backend/src/middleware - Auth module · Login and session flow exposed through controllers, routes, and service.
backend/src/modules/auth - Projects module · Project registration and management endpoints.
backend/src/modules/projects - Scans module · Scan submission, status, history, and result retrieval.
backend/src/modules/scans - Issues module · Vulnerability findings surfaced from scan output.
backend/src/modules/issues - Scan queue · BullMQ-style queue that decouples scan requests from processing.
backend/src/queue/scan.queue.ts - Scanner bridge · Bearer execution, parsing, and AI-assisted scan processing.
backend/src/scanner - AI providers · Abstracted Gemini, OpenAI, and NVIDIA providers with fallback behavior.
backend/src/modules/ai/ai.interface.ts - Prisma layer · 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 · System of record for auth state, scans, and findings.
- Redis · Queue backend for asynchronous scan execution.
- Bearer CLI · Static-analysis engine used to generate raw scan findings.
- LLM APIs · External model providers used to explain and summarize findings.
- OAuth provider · External identity provider used through Passport integration.
Connections 22
- 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.