# viralcodex/dephound architecture

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

- Interactive diagram: https://gitdiagram.com/viralcodex/dephound
- Repository: https://github.com/viralcodex/dephound

## Overview

##### Main Components
- **Frontend (Next.js)**: React-based UI under `src/app`, `src/components`, `src/hooks`, `src/lib`
- **Backend (Node + TypeScript)**: API server under `backend/server.ts`, `backend/service`, `backend/db`, `backend/prompts`
- **Database / Persistence**: Drizzle ORM configuration (`backend/drizzle.config.json`), schema & actions in `backend/db`
- **External Services**:
- OSV.dev (dependency vulnerability data)
- Gemini AI API (AI summarization & fix plans)

##### Relationships & Data Flow
- User interacts with the **Frontend** in the browser → sends HTTP requests to the **Backend**.
- The **Backend API** orchestrates:
a. Fetch vulnerability data (via OSV.dev)
b. Permits uploads of manifest files or GitHub URLs
c. Invokes the **AI Service** (Gemini API) to generate summaries or fix plans
d. Reads/writes to the **Database** for caching or user sessions (if applicable)
- Response data returns to the **Frontend**, which renders the graph visualization and AI dialogs.

##### Architectural Patterns
- **Separation of Concerns**: UI vs. API vs. Data layer
- **Service Layer** (`backend/service`): distinct services for agents, analysis, AI calls
- **Schema-Driven AI**: JSON schemas under `backend/prompts/schemas` enforce structured responses

**[ User Browser ]**

- v

- Frontend (Next.js) |
- src/app/pages    |
- components/*     |
- hooks, lib       |

- v

- API Layer          |
- backend/server.ts|
- routes/controllers|

- v

- Service Layer               |
- analysis_service.ts       |
- ai_service.ts             |
- agents_service.ts         |

- v

- Database  |<--->| OSV.dev API     |
- (Drizzle) |     | (vuln data)     |

- v

- Gemini AI API   |
- (summaries &    |
- fix plans)     |

##### Embedding in README
- Paste the ASCII/Markdown version under a “## Architecture” section

- ![DepHound.AI Architecture](./docs/architecture-vertical.png)

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User Browser"]:::user
    User --> F1

    subgraph "Frontend (Next.js)"
        direction TB
        F1["src/app"]:::frontend
        F2["src/components"]:::frontend
        F3["src/hooks"]:::frontend
        F4["src/lib"]:::frontend
        C1["dependency-diagram.tsx"]:::frontend
        C2["ai-dialog.tsx"]:::frontend
        P1["analyse/page.tsx"]:::frontend
        F2 --> C1
        F2 --> C2
        F1 --> P1
    end

    P1 --> Srv

    subgraph "API Layer"
        direction TB
        Srv["backend/server.ts"]:::backend
    end

    Srv --> ServiceLayer

    subgraph "Service Layer"
        direction TB
        SL1["analysis_service.ts"]:::backend
        SL2["ai_service.ts"]:::backend
        SL3["agents_service.ts"]:::backend
    end

    ServiceLayer --> SL1
    ServiceLayer --> SL2
    ServiceLayer --> SL3

    SL1 --> DBGroup
    SL1 --> OSV
    SL2 --> Gemini
    SL2 --> PSDir
    SL2 --> PR
    SL2 --> ENV
    SL2 --> CONST

    subgraph "Database / ORM"
        direction TB
        DB0["drizzle.config.json"]:::database
        DB1["db/schema.ts"]:::database
        DB2["db/db.ts"]:::database
        DB3["db/actions.ts"]:::database
    end

    DBGroup --> DB0
    DB0 --> DB1
    DB1 --> DB2
    DB2 --> DB3

    subgraph "Prompt Schemas"
        direction TB
        PSDir["backend/prompts/schemas"]:::backend
        PDS1["inlineai-summary-schema.json"]:::backend
        PDS2["vulnerability-summary-schema.json"]:::backend
        PDS3["vulnerability_fix_plan_response_schema.json"]:::backend
        PSDir --> PDS1
        PSDir --> PDS2
        PSDir --> PDS3
    end

    PR["backend/prompts/prompts.ts"]:::backend
    ENV["backend/config/env.ts"]:::backend
    CONST["backend/constants/constants.ts"]:::backend

    subgraph "External Services"
        direction TB
        OSV["OSV.dev API"]:::external
        Gemini["Gemini AI API"]:::external
    end

    classDef user fill:#e0f7fa,stroke:#000,color:#000
    classDef frontend fill:#bbdefb,stroke:#0d47a1,color:#000
    classDef backend fill:#c8e6c9,stroke:#1b5e20,color:#000
    classDef database fill:#eeeeee,stroke:#757575,color:#000
    classDef external fill:#ffe0b2,stroke:#e65100,color:#000

    click F1 "https://github.com/viralcodex/dephound/tree/main/src/app"
    click F2 "https://github.com/viralcodex/dephound/tree/main/src/components"
    click F3 "https://github.com/viralcodex/dephound/tree/main/src/hooks"
    click F4 "https://github.com/viralcodex/dephound/tree/main/src/lib"
    click C1 "https://github.com/viralcodex/dephound/blob/main/src/components/dependency-diagram.tsx"
    click C2 "https://github.com/viralcodex/dephound/blob/main/src/components/ai-dialog.tsx"
    click P1 "https://github.com/viralcodex/dephound/blob/main/src/app/analyse/page.tsx"
    click Srv "https://github.com/viralcodex/dephound/blob/main/backend/server.ts"
    click SL1 "https://github.com/viralcodex/dephound/blob/main/backend/service/analysis_service.ts"
    click SL2 "https://github.com/viralcodex/dephound/blob/main/backend/service/ai_service.ts"
    click SL3 "https://github.com/viralcodex/dephound/blob/main/backend/service/agents_service.ts"
    click DB0 "https://github.com/viralcodex/dephound/blob/main/backend/drizzle.config.json"
    click DB1 "https://github.com/viralcodex/dephound/blob/main/backend/db/schema.ts"
    click DB2 "https://github.com/viralcodex/dephound/blob/main/backend/db/db.ts"
    click DB3 "https://github.com/viralcodex/dephound/blob/main/backend/db/actions.ts"
    click PSDir "https://github.com/viralcodex/dephound/tree/main/backend/prompts/schemas"
    click PDS1 "https://github.com/viralcodex/dephound/blob/main/backend/prompts/schemas/inlineai-summary-schema.json"
    click PDS2 "https://github.com/viralcodex/dephound/blob/main/backend/prompts/schemas/vulnerability-summary-schema.json"
    click PDS3 "https://github.com/viralcodex/dephound/blob/main/backend/prompts/schemas/vulnerability_fix_plan_response_schema.json"
    click PR "https://github.com/viralcodex/dephound/blob/main/backend/prompts/prompts.ts"
    click ENV "https://github.com/viralcodex/dephound/blob/main/backend/config/env.ts"
    click CONST "https://github.com/viralcodex/dephound/blob/main/backend/constants/constants.ts"
```
