# dr-skaragiannis/nex architecture

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

- Interactive diagram: https://gitdiagram.com/dr-skaragiannis/nex
- Repository: https://github.com/dr-skaragiannis/nex

## Overview

NEX is an exposure-intelligence product: users review assets, findings, and scan history, configure provider credentials, and submit OSINT searches that discover exposed services and persist scan results. The combined deployment serves the dashboard and API from Next.js, with PostgreSQL/Drizzle storage; an optional proxy mode delegates API requests to the preserved FastAPI/SQLite backend. The map emphasizes integrated runtime paths and documented legacy capabilities; some unsampled provider and page internals are represented by their source directories.

Main entry points: [`src/server/repository.ts`](https://github.com/dr-skaragiannis/nex/blob/main/src/server/repository.ts) (Inventory repository), [`src/app/api/nex/[...path]/route.ts`](https://github.com/dr-skaragiannis/nex/blob/main/src/app/api/nex/%5B...path%5D/route.ts) (NEX API routes), [`src/dashboard/App.tsx`](https://github.com/dr-skaragiannis/nex/blob/main/src/dashboard/App.tsx) (Dashboard router), [`src/server/scan.ts`](https://github.com/dr-skaragiannis/nex/blob/main/src/server/scan.ts) (Live scan engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_web_entry["Next.js pages<br/>[page.tsx]"]
  node_dashboard_app["Dashboard router<br/>[App.tsx]"]
  node_dashboard_pages["Exposure views"]
  node_dashboard_settings["Provider settings<br/>[Settings.tsx]"]
  node_api_client["Dashboard API client<br/>[api.ts]"]
end

subgraph group_integrated["Integrated API"]
  node_api_route["NEX API routes<br/>[route.ts]"]
  node_scan_runtime["Live scan engine<br/>[scan.ts]"]
  node_provider_services["OSINT providers<br/>[scan.ts]"]
end

subgraph group_storage["Data and risk"]
  node_risk["Risk estimation<br/>[risk.ts]"]
  node_repository["Inventory repository<br/>[repository.ts]"]
  node_database[("PostgreSQL database<br/>[index.ts]")]
  node_schema["Data schema<br/>[schema.ts]"]
  node_snapshot["Initial snapshot<br/>[initial.ts]"]
end

subgraph group_legacy["Optional FastAPI"]
  node_fastapi["FastAPI service<br/>[main.py]"]
  node_legacy_routes["Assets, scans, findings"]
  node_legacy_database[("SQLite database<br/>[database.py]")]
  node_legacy_providers["OSINT adapters"]
  node_proxy_manager["Proxy rotation<br/>[proxy_manager.py]"]
end

node_user(("Operator"))
node_external_osint{{"OSINT services"}}

node_user -->|"opens dashboard"| node_web_entry
node_web_entry -->|"renders"| node_dashboard_app
node_dashboard_app -->|"routes to"| node_dashboard_pages
node_dashboard_app -->|"routes to"| node_dashboard_settings
node_dashboard_pages -->|"requests data"| node_api_client
node_dashboard_settings -->|"tests credentials"| node_api_client
node_api_client -->|"calls same-origin API"| node_api_route
node_api_route -->|"runs scans"| node_scan_runtime
node_api_route -->|"reads and updates"| node_repository
node_api_route -->|"estimates risk"| node_risk
node_scan_runtime -->|"persists scan results"| node_repository
node_scan_runtime -.->|"searches providers"| node_provider_services
node_provider_services -->|"queries OSINT"| node_external_osint
node_repository -->|"reads and writes"| node_database
node_repository -->|"uses tables"| node_schema
node_repository -->|"calculates scores"| node_risk
node_snapshot -->|"seeds inventory"| node_repository
node_api_route -->|"optionally proxies"| node_fastapi
node_fastapi -->|"registers routes"| node_legacy_routes
node_fastapi -->|"initializes and queries"| node_legacy_database
node_legacy_routes -->|"uses database"| node_legacy_database
node_legacy_routes -->|"uses scan services"| node_legacy_providers
node_legacy_providers -->|"searches providers"| node_external_osint
node_legacy_providers -.->|"may route requests"| node_proxy_manager

click node_web_entry "https://github.com/dr-skaragiannis/nex/blob/main/src/app/page.tsx"
click node_dashboard_app "https://github.com/dr-skaragiannis/nex/blob/main/src/dashboard/App.tsx"
click node_dashboard_pages "https://github.com/dr-skaragiannis/nex/tree/main/src/dashboard/pages"
click node_dashboard_settings "https://github.com/dr-skaragiannis/nex/blob/main/src/dashboard/pages/Settings.tsx"
click node_api_client "https://github.com/dr-skaragiannis/nex/blob/main/src/dashboard/lib/api.ts"
click node_api_route "https://github.com/dr-skaragiannis/nex/blob/main/src/app/api/nex/%5B...path%5D/route.ts"
click node_scan_runtime "https://github.com/dr-skaragiannis/nex/blob/main/src/server/scan.ts"
click node_provider_services "https://github.com/dr-skaragiannis/nex/blob/main/src/server/scan.ts"
click node_risk "https://github.com/dr-skaragiannis/nex/blob/main/src/server/risk.ts"
click node_repository "https://github.com/dr-skaragiannis/nex/blob/main/src/server/repository.ts"
click node_database "https://github.com/dr-skaragiannis/nex/blob/main/src/db/index.ts"
click node_schema "https://github.com/dr-skaragiannis/nex/blob/main/src/db/schema.ts"
click node_snapshot "https://github.com/dr-skaragiannis/nex/blob/main/src/server/initial.ts"
click node_fastapi "https://github.com/dr-skaragiannis/nex/blob/main/cyber-exposure-backend/src/main.py"
click node_legacy_routes "https://github.com/dr-skaragiannis/nex/tree/main/cyber-exposure-backend/src/routers"
click node_legacy_database "https://github.com/dr-skaragiannis/nex/blob/main/cyber-exposure-backend/src/database.py"
click node_legacy_providers "https://github.com/dr-skaragiannis/nex/tree/main/cyber-exposure-backend/src/services"
click node_proxy_manager "https://github.com/dr-skaragiannis/nex/blob/main/cyber-exposure-backend/src/services/proxy_manager.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_web_entry,node_dashboard_app,node_dashboard_pages,node_dashboard_settings,node_api_client toneBlue
class node_api_route,node_scan_runtime,node_provider_services toneAmber
class node_risk,node_repository,node_database,node_schema,node_snapshot toneMint
class node_fastapi,node_legacy_routes,node_legacy_database,node_legacy_providers,node_proxy_manager toneRose
class node_user,node_external_osint toneIndigo
```

## Components

### Dashboard

- [Next.js pages](https://github.com/dr-skaragiannis/nex/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Dashboard router](https://github.com/dr-skaragiannis/nex/blob/main/src/dashboard/App.tsx): `src/dashboard/App.tsx`
- [Exposure views](https://github.com/dr-skaragiannis/nex/tree/main/src/dashboard/pages): `src/dashboard/pages`
- [Provider settings](https://github.com/dr-skaragiannis/nex/blob/main/src/dashboard/pages/Settings.tsx): `src/dashboard/pages/Settings.tsx`
- [Dashboard API client](https://github.com/dr-skaragiannis/nex/blob/main/src/dashboard/lib/api.ts): `src/dashboard/lib/api.ts`

### Integrated API

- [NEX API routes](https://github.com/dr-skaragiannis/nex/blob/main/src/app/api/nex/%5B...path%5D/route.ts): `src/app/api/nex/[...path]/route.ts`
- [Live scan engine](https://github.com/dr-skaragiannis/nex/blob/main/src/server/scan.ts): `src/server/scan.ts`
- [OSINT providers](https://github.com/dr-skaragiannis/nex/blob/main/src/server/scan.ts): `src/server/scan.ts`

### Data and risk

- [Risk estimation](https://github.com/dr-skaragiannis/nex/blob/main/src/server/risk.ts): `src/server/risk.ts`
- [Inventory repository](https://github.com/dr-skaragiannis/nex/blob/main/src/server/repository.ts): `src/server/repository.ts`
- [PostgreSQL database](https://github.com/dr-skaragiannis/nex/blob/main/src/db/index.ts): `src/db/index.ts`
- [Data schema](https://github.com/dr-skaragiannis/nex/blob/main/src/db/schema.ts): `src/db/schema.ts`
- [Initial snapshot](https://github.com/dr-skaragiannis/nex/blob/main/src/server/initial.ts): `src/server/initial.ts`

### Optional FastAPI

- [FastAPI service](https://github.com/dr-skaragiannis/nex/blob/main/cyber-exposure-backend/src/main.py): `cyber-exposure-backend/src/main.py`
- [Assets, scans, findings](https://github.com/dr-skaragiannis/nex/tree/main/cyber-exposure-backend/src/routers): `cyber-exposure-backend/src/routers`
- [SQLite database](https://github.com/dr-skaragiannis/nex/blob/main/cyber-exposure-backend/src/database.py): `cyber-exposure-backend/src/database.py`
- [OSINT adapters](https://github.com/dr-skaragiannis/nex/tree/main/cyber-exposure-backend/src/services): `cyber-exposure-backend/src/services`
- [Proxy rotation](https://github.com/dr-skaragiannis/nex/blob/main/cyber-exposure-backend/src/services/proxy_manager.py): `cyber-exposure-backend/src/services/proxy_manager.py`

### Other components

- **Operator**
- **OSINT services**

## Connections

- Operator → Next.js pages: opens dashboard (evidence: `README.md`)
- Next.js pages → Dashboard router: renders (evidence: `src/app/page.tsx`)
- Dashboard router → Exposure views: routes to (evidence: `src/dashboard/App.tsx`)
- Dashboard router → Provider settings: routes to (evidence: `src/dashboard/App.tsx`)
- Exposure views → Dashboard API client: requests data (evidence: `README.md`)
- Provider settings → Dashboard API client: tests credentials (evidence: `README.md`)
- Dashboard API client → NEX API routes: calls same-origin API (evidence: `README.md`)
- NEX API routes → Live scan engine: runs scans (evidence: `src/app/api/nex/[...path]/route.ts`)
- NEX API routes → Inventory repository: reads and updates (evidence: `src/app/api/nex/[...path]/route.ts`)
- NEX API routes → Risk estimation: estimates risk (evidence: `src/app/api/nex/[...path]/route.ts`)
- Live scan engine → Inventory repository: persists scan results (evidence: `src/server/scan.ts`)
- Live scan engine → OSINT providers: searches providers (evidence: `src/server/scan.ts`)
- OSINT providers → OSINT services: queries OSINT (evidence: `README.md`)
- Inventory repository → PostgreSQL database: reads and writes (evidence: `src/server/repository.ts`)
- Inventory repository → Data schema: uses tables (evidence: `src/server/repository.ts`)
- Inventory repository → Risk estimation: calculates scores (evidence: `src/server/repository.ts`)
- Initial snapshot → Inventory repository: seeds inventory (evidence: `src/server/initial.ts`)
- NEX API routes → FastAPI service: optionally proxies (evidence: `README.md`)
- FastAPI service → Assets, scans, findings: registers routes (evidence: `cyber-exposure-backend/src/main.py`)
- FastAPI service → SQLite database: initializes and queries (evidence: `cyber-exposure-backend/src/main.py`)
- Assets, scans, findings → SQLite database: uses database (evidence: `cyber-exposure-backend/src/routers/assets.py`)
- Assets, scans, findings → OSINT adapters: uses scan services (evidence: `README.md`)
- OSINT adapters → OSINT services: searches providers (evidence: `README.md`)
- OSINT adapters → Proxy rotation: may route requests (evidence: `cyber-exposure-backend/src/services/shodan_client.py`)
