# vaibhav300503/soc-dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/vaibhav300503/soc-dashboard
- Repository: https://github.com/vaibhav300503/soc-dashboard

## Overview

1. **Overall shape**
   - This is a two-tier SOC platform: a **Vue 3 frontend** in `src/` and a **Node/Express backend** in `backend/`.
   - The backend is the system of record and integration layer; the frontend is a dashboard/analysis shell that consumes API data and renders charts, maps, tables, and real-time streams.

2. **Frontend presentation layer**
   - The UI is organized around route-driven pages such as Dashboard, GeoAnalytics, IpAnalytics, LogTypes, Severity, Endpoints, LogViewer, Tailscale, and Profile.
   - `src/components/soc/` holds the analytics widgets: maps, topology graphs, timelines, severity charts, tables, and notification panels.
   - State is managed with **Pinia stores** plus API/service wrappers, with Vue Router controlling page-level navigation.

3. **Frontend data access boundary**
   - The frontend does not talk directly to databases; it goes through `src/api/*` and `src/services/*`.
   - These API clients feed store modules like `apiStore`, `logStore`, `authStore`, and `userStore`, which then drive computed views in the pages/components.
   - The architecture is intentionally layered: API client → store → page → visualization component.

4. **Backend API layer**
   - `backend/routes/` is the main HTTP surface and is split by domain: logs, events, alerts, cases, auth, geo, IP management, lookup, export, topology, profile, agents, and multiple Tailscale-related routes.
   - This makes the backend the orchestration boundary between MongoDB, external enrichment services, alert/case integrations, and real-time delivery mechanisms.

5. **Persistence model**
   - The backend uses **MongoDB** with a model-per-collection approach under `backend/models/`.
   - Key persisted domains include logs, events, alerts, cases, users, blocked/safe IP lists, geo cache, topology data, and Tailscale devices/logs.
   - Several scripts and maintenance utilities indicate production concerns around indexing, migration, seeding, and data backfill.

6. **Security and request mediation**
   - Middleware enforces authentication, HMAC/signature checks, validation, log classification, geoIP enrichment, and Tailscale-specific request validation.
   - This suggests the backend is handling both interactive dashboard traffic and trusted ingestion from agents/streaming clients, with different trust levels at the edge.
   - `secureConfig` and `secureLogger` indicate sensitive configuration and audit-friendly logging are treated as first-class concerns.

7. **Real-time and streaming subsystem**
   - The repo supports live updates through both **SSE-style streaming** and **WebSocket-based routes/services**.
   - Tailscale has the most explicit real-time path: server-side stream services, websocket manager, protected websocket routes, and frontend stream/websocket clients.
   - This is the boundary for “live SOC” behavior: incoming telemetry is pushed to clients instead of waiting for page refreshes.

8. **Tailscale integration**
   - Tailscale is a dedicated subsystem spanning agents, sync services, streaming, routes, and models.
   - The presence of host-side agents (`tailscale-agent.py`, `tailscale-live-streamer.py`, systemd service) implies telemetry is collected from endpoints and forwarded into the backend.
   - The dashboard then surfaces device status, peer connections, sessions, subnet routers, exit nodes, and Tailscale logs as a separate operational domain.

9. **Geo and threat enrichment**
   - Geo enrichment is a backend service concern, not just a UI feature: IPs are enriched, cached, and stored for reuse.
   - The backend also exposes lookup endpoints for WHOIS/GeoIP/threat-intel style queries, and the frontend uses them for geographic and IP-centric investigation views.
   - This is a clear enrichment pipeline: raw event/log data → IP enrichment/cache → geo summaries/maps → analyst views.

10. **Alerts, cases, and external integrations**
   - Alerting is modeled as rules plus generated alert events, with streaming support for notifications.
   - Case management is separate and synchronized through services like `caseService`, `caseSync`, and integration modules for **TheHive** and **Cortex**.
   - This indicates the SOC dashboard is not isolated; it can feed or mirror incident workflows in external security platforms.

11. **Operational/maintenance tooling**
   - The backend includes many scripts for seeding, validation, migration, cleanup, severity recalculation, and Tailscale import/testing.
   - These scripts show the system expects ongoing data hygiene and schema evolution, especially around log classification, severity normalization, and index management.
   - There are also agent/service files and proxy/exposure tools in `tools/`, suggesting deployment into mixed local/networked environments.

12. **Main data flow for diagramming**
   - Primary path: **agents/external sources → backend ingestion/routes → MongoDB collections/models → API responses → Pinia stores → Vue pages/components**.
   - Secondary paths: **backend enrichment/integration services** augment data before it reaches the UI; **streaming services** push updates directly to connected clients; **alert/case integrations** export security events to external systems.
   - The key architectural boundary is between the browser UI and the backend API/streaming layer; almost everything operational crosses that boundary through authenticated, validated routes.

Main entry points: [`backend/services/geoEnrichment.js`](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/services/geoEnrichment.js) (Core Services), [`backend/routes/logs.js`](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/routes/logs.js) (API Routes), [`backend/models/Log.js`](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/models/Log.js) (Mongo Models), [`backend/routes/tailscale.js`](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/routes/tailscale.js) (Tailscale API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui["Vue App<br/>frontend shell<br/>[App.vue]"]
  node_router["Router<br/>navigation<br/>[index.js]"]
  node_pages["SOC Pages<br/>views<br/>[Dashboard.vue]"]
  node_soccomponents["SOC Visuals<br/>visual components<br/>[GeoMap.vue]"]
  node_stores["Pinia Stores<br/>state<br/>[apiStore.js]"]
  node_api["API Clients<br/>data access<br/>[index.js]"]
  node_streamclients["Stream Clients<br/>realtime clients"]
end

subgraph group_backend["Backend"]
  node_backendserver["Express Server<br/>api host<br/>[server.js]"]
  node_middleware["Edge Middleware<br/>request mediation<br/>[authMiddleware.js]"]
  node_routes["API Routes<br/>http surface<br/>[logs.js]"]
  node_services["Core Services<br/>domain services<br/>[geoEnrichment.js]"]
  node_models[("Mongo Models<br/>persistence<br/>[Log.js]")]
  node_db[("MongoDB<br/>database<br/>[db.js]")]
  node_external["External Intel<br/>integrations"]
  node_secureconfig["Secure Config<br/>[secureConfig.js]"]
  node_tailroutes["Tailscale API<br/>realtime api<br/>[tailscale.js]"]
  node_tailscale["Tailscale Services<br/>sync/stream<br/>[tailscale.js]"]
  node_lookup["Geo/IP Lookup<br/>enrichment api<br/>[lookup.js]"]
end

subgraph group_ops["Operations"]
  node_agents["Tailscale Agents<br/>endpoint collectors<br/>[tailscale-agent.py]"]
  node_maint["Maintenance Scripts<br/>ops scripts<br/>[seed-mongodb.js]"]
end

node_ui -->|"uses"| node_router
node_router -->|"loads"| node_pages
node_pages -->|"renders"| node_soccomponents
node_pages -->|"reads state"| node_stores
node_stores -->|"fetches"| node_api
node_api -->|"http"| node_backendserver
node_streamclients -->|"realtime"| node_tailroutes
node_backendserver -->|"passes through"| node_middleware
node_middleware -->|"protects"| node_routes
node_routes -->|"orchestrates"| node_services
node_routes -->|"reads/writes"| node_models
node_models -->|"stored in"| node_db
node_services -->|"updates"| node_models
node_services -->|"integrates"| node_external
node_agents -->|"ingests"| node_tailroutes
node_tailroutes -->|"delegates"| node_tailscale
node_tailscale -->|"persists"| node_models
node_lookup -->|"enriches"| node_services
node_maint -.->|"maintains"| node_db
node_secureconfig -.->|"configures"| node_backendserver
node_services -->|"streams"| node_tailroutes
node_routes -->|"exposes"| node_lookup

click node_ui "https://github.com/vaibhav300503/soc-dashboard/blob/main/src/App.vue"
click node_router "https://github.com/vaibhav300503/soc-dashboard/blob/main/src/router/index.js"
click node_pages "https://github.com/vaibhav300503/soc-dashboard/blob/main/src/pages/Dashboard.vue"
click node_soccomponents "https://github.com/vaibhav300503/soc-dashboard/blob/main/src/components/soc/GeoMap.vue"
click node_stores "https://github.com/vaibhav300503/soc-dashboard/blob/main/src/stores/apiStore.js"
click node_api "https://github.com/vaibhav300503/soc-dashboard/blob/main/src/api/index.js"
click node_streamclients "https://github.com/vaibhav300503/soc-dashboard/blob/main/src/services/tailscaleStreamService.js"
click node_backendserver "https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/server.js"
click node_middleware "https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/middleware/authMiddleware.js"
click node_routes "https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/routes/logs.js"
click node_services "https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/services/geoEnrichment.js"
click node_models "https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/models/Log.js"
click node_db "https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/config/db.js"
click node_external "https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/services/thehiveIntegration.js"
click node_agents "https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/agents/tailscale-agent.py"
click node_maint "https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/scripts/seed-mongodb.js"
click node_secureconfig "https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/config/secureConfig.js"
click node_tailroutes "https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/routes/tailscale.js"
click node_tailscale "https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/services/tailscale.js"
click node_lookup "https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/routes/lookup.js"

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_ui,node_router,node_pages,node_soccomponents,node_stores,node_api,node_streamclients toneBlue
class node_backendserver,node_middleware,node_routes,node_services,node_models,node_db,node_external,node_secureconfig,node_tailroutes,node_tailscale,node_lookup toneAmber
class node_agents,node_maint toneMint
```

## Components

### Frontend

Vue dashboard, route pages, state, and visual analytics

- [Vue App](https://github.com/vaibhav300503/soc-dashboard/blob/main/src/App.vue): frontend shell · Root Vue 3 application and composition entrypoint · `src/App.vue`
- [Router](https://github.com/vaibhav300503/soc-dashboard/blob/main/src/router/index.js): navigation · Route definitions and navigation guards · `src/router/index.js`
- [SOC Pages](https://github.com/vaibhav300503/soc-dashboard/blob/main/src/pages/Dashboard.vue): views · Dashboard, analytics, viewer, profile, and Tailscale pages · `src/pages/Dashboard.vue`
- [SOC Visuals](https://github.com/vaibhav300503/soc-dashboard/blob/main/src/components/soc/GeoMap.vue): visual components · Maps, graphs, charts, tables, timelines, and notification panels · `src/components/soc/GeoMap.vue`
- [Pinia Stores](https://github.com/vaibhav300503/soc-dashboard/blob/main/src/stores/apiStore.js): state · Client state for auth, logs, search, API data, and users · `src/stores/apiStore.js`
- [API Clients](https://github.com/vaibhav300503/soc-dashboard/blob/main/src/api/index.js): data access · HTTP clients and interceptors used by the UI · `src/api/index.js`
- [Stream Clients](https://github.com/vaibhav300503/soc-dashboard/blob/main/src/services/tailscaleStreamService.js): realtime clients · Tailscale websocket and stream clients for live updates · `src/services/tailscaleStreamService.js`

### Backend

Express API, persistence, middleware, and services

- [Express Server](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/server.js): api host · Main backend entrypoint wiring routes, middleware, and services · `backend/server.js`
- [Edge Middleware](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/middleware/authMiddleware.js): request mediation · Auth, HMAC, validation, geoIP, log classification, and Tailscale checks · `backend/middleware/authMiddleware.js`
- [API Routes](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/routes/logs.js): http surface · Domain routes for logs, alerts, cases, geo, IP, profile, agents, and Tailscale · `backend/routes/logs.js`
- [Core Services](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/services/geoEnrichment.js): domain services · Geo enrichment, case sync, alert integrations, metrics, websockets, and Tailscale workflows · `backend/services/geoEnrichment.js`
- [Mongo Models](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/models/Log.js): persistence · Collections for logs, events, alerts, cases, users, geo cache, IP lists, and Tailscale data · `backend/models/Log.js`
- [MongoDB](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/config/db.js): database · Primary system of record for operational and investigative data · `backend/config/db.js`
- [External Intel](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/services/thehiveIntegration.js): integrations · TheHive, Cortex, enrichment sources, and remote telemetry clients · `backend/services/thehiveIntegration.js`
- [Secure Config](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/config/secureConfig.js): config · Sensitive configuration and audit-oriented logging support · `backend/config/secureConfig.js`
- [Tailscale API](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/routes/tailscale.js): realtime api · Dedicated Tailscale routes plus protected websocket and stream endpoints · `backend/routes/tailscale.js`
- [Tailscale Services](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/services/tailscale.js): sync/stream · Device sync, stream handling, websocket management, and protected delivery · `backend/services/tailscale.js`
- [Geo/IP Lookup](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/routes/lookup.js): enrichment api · Lookup and geo/threat investigation endpoints · `backend/routes/lookup.js`

### Operations

Agents, scripts, and deployment helpers

- [Tailscale Agents](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/agents/tailscale-agent.py): endpoint collectors · Host-side telemetry collectors and live streamers · `backend/agents/tailscale-agent.py`
- [Maintenance Scripts](https://github.com/vaibhav300503/soc-dashboard/blob/main/backend/scripts/seed-mongodb.js): ops scripts · Seeding, migration, backfill, validation, and cleanup tooling · `backend/scripts/seed-mongodb.js`

## Connections

- Vue App → Router: uses · Root app mounts routed navigation
- Router → SOC Pages: loads · Routes select dashboard and investigation pages
- SOC Pages → SOC Visuals: renders · Pages compose charts, maps, tables, and timelines
- SOC Pages → Pinia Stores: reads state · Views consume Pinia state for data and filters
- Pinia Stores → API Clients: fetches · Stores hydrate from API clients
- API Clients → Express Server: http · Frontend API calls reach the backend server
- Stream Clients → Tailscale API: realtime · Live UI connects to Tailscale stream/websocket endpoints
- Express Server → Edge Middleware: passes through · Requests are mediated before route handling
- Edge Middleware → API Routes: protects · Authentication, validation, and enrichment guard the HTTP surface
- API Routes → Core Services: orchestrates · Routes delegate business logic and integrations
- API Routes → Mongo Models: reads/writes · API handlers persist and query domain records
- Mongo Models → MongoDB: stored in · Collections are backed by MongoDB
- Core Services → Mongo Models: updates · Services synchronize caches, cases, alerts, and Tailscale state
- Core Services → External Intel: integrates · Backend talks to enrichment and incident platforms
- Tailscale Agents → Tailscale API: ingests · Endpoint collectors feed Tailscale telemetry into the backend
- Tailscale API → Tailscale Services: delegates · Dedicated routes hand off to sync and websocket services
- Tailscale Services → Mongo Models: persists · Tailscale devices and logs are stored in MongoDB
- Geo/IP Lookup → Core Services: enriches · Geo and threat lookup endpoints reuse backend enrichment logic
- Maintenance Scripts → MongoDB: maintains · Scripts seed, migrate, validate, and backfill stored data
- Secure Config → Express Server: configures · Sensitive configuration and logging settings shape runtime behavior
- Core Services → Tailscale API: streams · Realtime services feed server-sent and websocket updates
- API Routes → Geo/IP Lookup: exposes · HTTP surface includes investigation and enrichment endpoints