# shlokdhawan/depshield architecture

> Architecture diagram of the GitHub repository shlokdhawan/depshield, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shlokdhawan/depshield
- Repository: https://github.com/shlokdhawan/depshield

## Overview

1. **High-level shape**
   - DepShield is a **two-tier application**: a **React/Vite frontend** in `src/` and a **Python backend** in `backend/`.
   - The frontend is the interactive dashboard; the backend owns analysis, scoring, persistence, and integrations with external security/identity services.

2. **Frontend boundary**
   - The UI is a single-page app built with **React** and **Vite**.
   - Core entry points are `src/main.jsx` and `src/App.jsx`, with styling via Tailwind/PostCSS (`tailwind.config.js`, `postcss.config.js`, `src/index.css`).
   - The frontend is organized around reusable components in `src/components/`, including:
     - `MonitoringDashboard.jsx` for the main results view
     - `Graph.jsx` for dependency/risk visualization
     - `GitHubLoginButton.jsx`, `UserMenu.jsx` for auth UX
     - `Panel.jsx`, `UI.jsx` for layout primitives

3. **Frontend state and API access**
   - `src/contexts/AuthContext.jsx` likely centralizes user/session state and gates access to protected UI.
   - `src/config/api.js` is the frontend’s boundary to the backend API, keeping request URLs/details out of components.
   - `src/components/Data.js` appears to hold or shape dashboard data passed into visualization components.

4. **Backend service boundary**
   - `backend/app.py` is the backend entry point and likely exposes the HTTP API consumed by the frontend.
   - The backend is a **Flask** service, per the README and file layout.
   - It acts as the orchestration layer for analysis rather than just a CRUD API.

5. **Authentication and identity**
   - `backend/auth.py` and `backend/github_app.py` indicate GitHub-based identity/integration is part of the system.
   - The frontend’s GitHub login button and auth context suggest the main user boundary is **GitHub-authenticated access** to dependency analysis.
   - This is likely the trust boundary for accessing repo-specific data and stored results.

6. **Analysis pipeline**
   - `backend/analyzer.py` is the central orchestrator for turning dependency inputs into risk findings.
   - Specialized modules split the analysis stages:
     - `vuln_classifier.py` for categorizing findings
     - `scoring.py` for severity/risk scoring
     - `summarizer.py` for human-readable summaries
     - `hf_ner.py` for entity extraction from text
   - This suggests a pipeline that combines structured vulnerability data with AI/ML-assisted enrichment.

7. **Security/threat intelligence integrations**
   - `backend/nvd_client.py` integrates with the **NVD** vulnerability database.
   - `backend/threat_intel.py` likely aggregates or normalizes threat signals from one or more external sources.
   - `backend/rag_client.py` suggests a retrieval-augmented generation layer for explanation or enrichment of findings.
   - Together these modules separate external intelligence retrieval from the core scoring logic.

8. **Persistence layer**
   - `backend/db_adapter.py`, `backend/supabase_client.py`, and `backend/supabase_schema.sql` show that **Supabase** is used as the backing data store/service.
   - The adapter pattern indicates the backend does not couple business logic directly to the database vendor.
   - Likely persisted data includes user/account linkage, scan history, and analysis outputs.

9. **Data flow from user action to dashboard**
   - A user authenticates in the frontend, initiates or views an analysis, and the React app calls the Flask API.
   - The backend gathers dependency/security data, runs classification and scoring, optionally enriches it with AI/RAG, then stores or returns the results.
   - The frontend then renders the result set in the dashboard and dependency graph views.

10. **Project execution model**
   - The repo is designed to run both tiers together in development: the README says `npm start` launches the Vite frontend and the Flask backend concurrently.
   - Separate commands exist for frontend (`npm run dev`) and backend (`npm run backend`), reinforcing the clear service split.
   - Dependencies are managed with `package-lock.json`/`requirements.txt`, so the runtime is mixed Node.js + Python.

11. **Deployment and ops**
   - `Dockerfile` indicates containerized deployment support.
   - `render.yaml` suggests a Render deployment target or service definition.
   - `.github/workflows/depshield.yml` provides CI automation, likely for checks/builds around the dependency-risk workflow.

12. **Testing and validation**
   - The repository includes multiple Python test and verification scripts such as `test_osv.py`, `test_score.py`, and `verify_final_score.py`.
   - This points to a backend-heavy validation surface, especially around vulnerability matching and scoring correctness.
   - The `scratch/` and `.cache/` directories appear to hold local experimentation and should not be treated as core architecture.

13. **What an architecture diagram should show**
   - Draw a **React frontend** with auth, dashboard, graph, and API client modules.
   - Draw a **Flask backend** with an analysis/orchestration core, external intelligence clients, and persistence via Supabase.
   - Show external dependencies on **GitHub**, **NVD**, and Supabase, with the backend as the main integration point.
   - Emphasize that the UI is presentation and interaction only; the backend owns all security analysis and scoring decisions.

Main entry points: [`src/App.jsx`](https://github.com/shlokdhawan/depshield/blob/main/src/App.jsx) (App), [`backend/analyzer.py`](https://github.com/shlokdhawan/depshield/blob/main/backend/analyzer.py) (Analyzer), [`backend/app.py`](https://github.com/shlokdhawan/depshield/blob/main/backend/app.py) (app), [`backend/db_adapter.py`](https://github.com/shlokdhawan/depshield/blob/main/backend/db_adapter.py) (Persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_src_main(("main<br/>Vite entry<br/>[main.jsx]"))
  node_src_app["App<br/>React shell<br/>[App.jsx]"]
  node_auth_context["Auth<br/>session state<br/>[AuthContext.jsx]"]
  node_api_client["API client<br/>HTTP boundary<br/>[api.js]"]
  node_dashboard["Dashboard<br/>results view"]
  node_graph_view["Graph<br/>risk viz<br/>[Graph.jsx]"]
  node_login_button["GitHub login<br/>auth control"]
  node_user_menu["User menu<br/>auth UI<br/>[UserMenu.jsx]"]
  node_panel_ui["Panel<br/>layout primitive<br/>[Panel.jsx]"]
  node_ui_primitives["UI kit<br/>presentational components<br/>[UI.jsx]"]
end

subgraph group_backend["Backend"]
  node_backend_app(("app<br/>Flask API<br/>[app.py]"))
  node_backend_auth["Auth<br/>[auth.py]"]
  node_analyzer["Analyzer<br/>analysis orchestrator<br/>[analyzer.py]"]
  node_classify_score["Classify/score<br/>risk pipeline<br/>[vuln_classifier.py]"]
  node_enrichment["Enrichment<br/>nlp+rags<br/>[summarizer.py]"]
  node_intel_clients["Intel clients<br/>external data access<br/>[nvd_client.py]"]
  node_persistence["Persistence<br/>storage adapter<br/>[db_adapter.py]"]
end

subgraph group_external["External services"]
  node_github_api(("GitHub<br/>identity/integration"))
  node_nvd[("NVD<br/>vuln database")]
  node_supabase[("Supabase<br/>managed datastore")]
end

node_src_main -->|"mounts"| node_src_app
node_src_app -->|"uses"| node_auth_context
node_src_app -->|"calls"| node_api_client
node_src_app -->|"renders"| node_dashboard
node_src_app -->|"renders"| node_graph_view
node_src_app -->|"exposes"| node_login_button
node_src_app -->|"exposes"| node_user_menu
node_dashboard -->|"composes"| node_panel_ui
node_graph_view -->|"composes"| node_ui_primitives
node_login_button -->|"authenticates"| node_github_api
node_backend_app -->|"uses"| node_backend_auth
node_backend_app -->|"dispatches"| node_analyzer
node_analyzer -->|"feeds"| node_classify_score
node_analyzer -->|"enriches"| node_enrichment
node_analyzer -->|"queries"| node_intel_clients
node_intel_clients -->|"reads"| node_nvd
node_backend_auth -->|"integrates"| node_github_api
node_analyzer -->|"stores"| node_persistence
node_persistence -->|"writes"| node_supabase
node_api_client -->|"requests"| node_backend_app
node_backend_app -->|"reads/writes"| node_persistence

click node_src_main "https://github.com/shlokdhawan/depshield/blob/main/src/main.jsx"
click node_src_app "https://github.com/shlokdhawan/depshield/blob/main/src/App.jsx"
click node_auth_context "https://github.com/shlokdhawan/depshield/blob/main/src/contexts/AuthContext.jsx"
click node_api_client "https://github.com/shlokdhawan/depshield/blob/main/src/config/api.js"
click node_dashboard "https://github.com/shlokdhawan/depshield/blob/main/src/components/MonitoringDashboard.jsx"
click node_graph_view "https://github.com/shlokdhawan/depshield/blob/main/src/components/Graph.jsx"
click node_login_button "https://github.com/shlokdhawan/depshield/blob/main/src/components/GitHubLoginButton.jsx"
click node_user_menu "https://github.com/shlokdhawan/depshield/blob/main/src/components/UserMenu.jsx"
click node_panel_ui "https://github.com/shlokdhawan/depshield/blob/main/src/components/Panel.jsx"
click node_ui_primitives "https://github.com/shlokdhawan/depshield/blob/main/src/components/UI.jsx"
click node_backend_app "https://github.com/shlokdhawan/depshield/blob/main/backend/app.py"
click node_backend_auth "https://github.com/shlokdhawan/depshield/blob/main/backend/auth.py"
click node_analyzer "https://github.com/shlokdhawan/depshield/blob/main/backend/analyzer.py"
click node_classify_score "https://github.com/shlokdhawan/depshield/blob/main/backend/vuln_classifier.py"
click node_enrichment "https://github.com/shlokdhawan/depshield/blob/main/backend/summarizer.py"
click node_intel_clients "https://github.com/shlokdhawan/depshield/blob/main/backend/nvd_client.py"
click node_persistence "https://github.com/shlokdhawan/depshield/blob/main/backend/db_adapter.py"

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_src_main,node_src_app,node_auth_context,node_api_client,node_dashboard,node_graph_view,node_login_button,node_user_menu,node_panel_ui,node_ui_primitives toneBlue
class node_backend_app,node_backend_auth,node_analyzer,node_classify_score,node_enrichment,node_intel_clients,node_persistence toneAmber
class node_github_api,node_nvd,node_supabase toneMint
```

## Components

### Frontend

React/Vite dashboard and UI state

- [main](https://github.com/shlokdhawan/depshield/blob/main/src/main.jsx): Vite entry · Bootstraps the React app · `src/main.jsx`
- [App](https://github.com/shlokdhawan/depshield/blob/main/src/App.jsx): React shell · Top-level UI composition and routing · `src/App.jsx`
- [Auth](https://github.com/shlokdhawan/depshield/blob/main/src/contexts/AuthContext.jsx): session state · Centralizes signed-in user and access state · `src/contexts/AuthContext.jsx`
- [API client](https://github.com/shlokdhawan/depshield/blob/main/src/config/api.js): HTTP boundary · Frontend request wrapper for backend calls · `src/config/api.js`
- [Dashboard](https://github.com/shlokdhawan/depshield/blob/main/src/components/MonitoringDashboard.jsx): results view · Main monitoring and findings display · `src/components/MonitoringDashboard.jsx`
- [Graph](https://github.com/shlokdhawan/depshield/blob/main/src/components/Graph.jsx): risk viz · Dependency and risk visualization · `src/components/Graph.jsx`
- [GitHub login](https://github.com/shlokdhawan/depshield/blob/main/src/components/GitHubLoginButton.jsx): auth control · User sign-in entry point · `src/components/GitHubLoginButton.jsx`
- [User menu](https://github.com/shlokdhawan/depshield/blob/main/src/components/UserMenu.jsx): auth UI · Signed-in account and session actions · `src/components/UserMenu.jsx`
- [Panel](https://github.com/shlokdhawan/depshield/blob/main/src/components/Panel.jsx): layout primitive · Reusable content container · `src/components/Panel.jsx`
- [UI kit](https://github.com/shlokdhawan/depshield/blob/main/src/components/UI.jsx): presentational components · Shared frontend UI helpers · `src/components/UI.jsx`

### Backend

Flask analysis service and integrations

- [app](https://github.com/shlokdhawan/depshield/blob/main/backend/app.py): Flask API · Backend HTTP entry point · `backend/app.py`
- [Auth](https://github.com/shlokdhawan/depshield/blob/main/backend/auth.py): GitHub auth · Backend authentication and identity handling · `backend/auth.py`
- [Analyzer](https://github.com/shlokdhawan/depshield/blob/main/backend/analyzer.py): analysis orchestrator · Coordinates dependency analysis and findings generation · `backend/analyzer.py`
- [Classify/score](https://github.com/shlokdhawan/depshield/blob/main/backend/vuln_classifier.py): risk pipeline · Categorizes findings and computes severity · `backend/vuln_classifier.py`
- [Enrichment](https://github.com/shlokdhawan/depshield/blob/main/backend/summarizer.py): nlp+rags · Summaries, entity extraction, and retrieval-based context · `backend/summarizer.py`
- [Intel clients](https://github.com/shlokdhawan/depshield/blob/main/backend/nvd_client.py): external data access · Fetches vulnerability and threat signals from external sources · `backend/nvd_client.py`
- [Persistence](https://github.com/shlokdhawan/depshield/blob/main/backend/db_adapter.py): storage adapter · Database abstraction and Supabase integration · `backend/db_adapter.py`

### External services

Identity, intelligence, and storage systems outside the repo

- **GitHub**: identity/integration · External GitHub authentication and app integration
- **NVD**: vuln database · External vulnerability intelligence source
- **Supabase**: managed datastore · Back-end data storage and schema host

## Connections

- main → App: mounts · Bootstraps the React application
- App → Auth: uses · Reads session state and auth gates
- App → API client: calls · Triggers backend requests
- App → Dashboard: renders · Shows analysis results
- App → Graph: renders · Shows dependency risk graph
- App → GitHub login: exposes · Provides sign-in entry point
- App → User menu: exposes · Provides account controls
- Dashboard → Panel: composes · Uses shared layout container
- Graph → UI kit: composes · Uses shared UI helpers
- GitHub login → GitHub: authenticates · Starts GitHub-based login flow
- app → Auth: uses · Validates identity and access
- app → Analyzer: dispatches · Routes analysis requests
- Analyzer → Classify/score: feeds · Hands off findings for categorization and scoring
- Analyzer → Enrichment: enriches · Adds summaries and entity extraction
- Analyzer → Intel clients: queries · Pulls vulnerability and threat intelligence
- Intel clients → NVD: reads · Fetches external vulnerability data
- Auth → GitHub: integrates · Uses GitHub as the identity boundary
- Analyzer → Persistence: stores · Persists analysis outputs and scan state
- Persistence → Supabase: writes · Uses Supabase-backed storage
- API client → app: requests · Frontend API boundary to Flask service
- app → Persistence: reads/writes · Loads and saves analysis data