Architecture

Architecture

Gardik is a single Next.js 16 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 Better Auth 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)/. See Authentication.

API routes. src/app/api/**/route.ts handle all mutations and external integrations: alerts, credentials, dashboard config/presets, directory connections, employee scans, report export, roles and users, SSO, audit, SCIM, and webhooks. Every route authorizes through a single guard module (src/lib/apiAuth.ts), which resolves the caller's permissions rather than a role name. A coverage test fails the build if a mutating route is not mapped in src/lib/rbac/route-permissions.ts. See Roles and Permissions.

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

Module	Responsibility
auth/	Better Auth server config, sessions, invitations, 2FA gate
rbac/	Permission vocabulary, role presets, escalation and step-up rules, audit writer
sso/	OIDC provider management, config encryption, tenant guard, sign-in policy
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, notify/, email.ts	Outbound notification channels
integrations/, siem.ts	SIEM export (CEF/syslog/json) and push
remediation.ts	Directory remediation orchestration and audit
register.ts, gdpr.ts	GDPR exposure register and 72h deadlines
reportSchedules.ts, scheduler.ts	Scheduled report delivery, due-work checks
rateLimit.ts	Fixed-window rate limiter, backed by the RateLimit and ApiRateLimit tables
csp.ts	Per-request nonce and strict Content-Security-Policy
ssrf.ts	Outbound URL validation for webhook targets
validators.ts	Shared input validation
widgetRegistry.ts, dashboard.ts	Widget catalog and layout helpers

Time-driven work (auto scan/sync, scheduled reports, SIEM push) is triggered by an external scheduler hitting POST /api/cron; there is no long-running daemon. See Configuration.

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,
                            register, reports, data-sources, data-api,
                            notifications, access, security, 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
    auth/                   Better Auth setup, sessions, invitations
    rbac/                   Permissions, roles, step-up, audit
    sso/                    OIDC providers and sign-in policy
  types/                    Shared types
  middleware.ts             Route protection
prisma/
  schema.prisma             Data model
  migrations/               SQL migrations
  seed.ts, seed.dev.ts      Admin + demo seeders