Architecture

Architecture

DataShield is a single Next.js 15 application (App Router) backed by PostgreSQL through Prisma. There is no separate backend service: server logic lives in route handlers (src/app/api/**) and server-only library modules (src/lib/**).

High-level flow

flowchart LR
  IdP[Identity provider\nEntra / Google / LDAP / AWS / Okta] -->|pull sync| Sync[Directory sync]
  IdP2[IdP push] -->|SCIM 2.0| Scim[SCIM endpoint]
  Sync --> DB[(PostgreSQL)]
  Scim --> DB
  DB --> Scan[Scan engine]
  Providers[Breach providers\nHIBP / DeHashed / LeakCheck / IntelX / Snusbase] --> Scan
  Scan --> DB
  Scan --> Email[Email alerts]
  Scan --> Hooks[Webhooks]
  DB --> Dash[Dashboard + widgets]
  DB --> Reports[Reports + CSV export]

Loading

Layers

Routing and middleware. src/middleware.ts wraps Auth.js and protects every route except api/auth, static assets, and /login. Authenticated pages live under src/app/(dashboard)/, the login screen under src/app/(auth)/.

API routes. src/app/api/**/route.ts handle all mutations and external integrations: alerts, credentials, dashboard config/presets, directory connections, employee scans, report export, SCIM, and webhooks. Every route authorizes through a single guard module (src/lib/apiAuth.ts).

Library modules (src/lib). Server-only business logic, grouped by domain:

Module	Responsibility
scan/	Breach scan engine, provider registry, normalization
directory/	IdP connectors, sync, encryption, SCIM auth
reports/	Report aggregation, filters, CSV, comparison windows
credentials/	API key storage and provider metadata
alerts.ts, employees.ts	Domain queries
risk.ts	Risk-score calculation and level mapping
webhooks.ts, email.ts	Outbound notifications
rateLimit.ts	In-memory fixed-window rate limiter
widgetRegistry.ts, dashboard.ts	Widget catalog and layout helpers

UI (src/components). Grouped by feature: dashboard/ (widgets + canvas), reports/, employees/, alerts/, credentials/, settings/, layout/, and shared ui/. Dashboard state flows through React contexts (src/contexts/DashboardConfigContext, DashboardEditContext).

Multi-tenancy

Every domain row carries a companyId. A Company owns its users, employees, alerts, dashboard presets, directory connections, API credentials, and webhooks. Authorization always scopes queries to the session's companyId, so tenants never see each other's data. See Database Schema.

Directory structure

src/
  app/
    (auth)/login/           Login page
    (dashboard)/            Authenticated pages (dashboard, alerts, employees,
                            reports, data-sources, data-api, setup)
    api/                    Route handlers (REST + SCIM)
  components/               Feature-grouped React components
  contexts/                 Dashboard config + edit contexts
  hooks/                    Widget config/title hooks
  lib/                      Server-only domain logic
  types/                    Shared + next-auth type augmentation
  auth.ts, auth.config.ts   Auth.js setup
  middleware.ts             Route protection
prisma/
  schema.prisma             Data model
  migrations/               SQL migrations
  seed.ts, seed.dev.ts      Admin + demo seeders