vaibhav300503/soc-dashboard

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.