Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
87 lines (67 loc) · 2.39 KB

ARCHITECTURE.md

File metadata and controls

87 lines (67 loc) · 2.39 KB

Architecture

High-Level Design

OpsNexus ERP uses a split frontend/backend architecture:

  • Frontend: Next.js App Router (frontend)
  • Backend: Hono API server (backend)
  • Database: PostgreSQL via Drizzle ORM (drizzle/schema.ts)
  • Authentication: Better Auth session cookies
  • Realtime events: Supabase broadcast channels
  • File uploads: UploadThing + claim file records in Postgres

Runtime Components

Frontend

  • Role-based pages:
    • /admin/*
    • /supervisor
    • /operator
    • /portal
  • API client: Axios instance with withCredentials: true
  • Auth client: Better Auth React client
  • Realtime UI notifications subscribed via Supabase client

Backend

  • Entry point: backend/src/server/index.ts
  • Global middleware:
    • CORS
    • session extraction (auth.api.getSession)
  • Domain routers:
    • products
    • leads
    • clients
    • claims
    • users
    • analytics
    • operator
    • supervisor
    • portal

Data Model

Schema source of truth: drizzle/schema.ts.

Core entities:

  • users: user identities and roles
  • accounts, sessions, verifications: Better Auth tables
  • products: catalog
  • leads: pre-sale records
  • lead_products: products attached to leads
  • clients: post-conversion client records
  • client_products: sold/assigned products for clients
  • claims: post-sale issues
  • claim_files: claim attachments
  • comments: discussion threads for leads/claims/clients/assignments

RBAC Model

Roles:

  • admin: full operational and user control
  • supervisor: team-level visibility and assignments
  • operator: assigned leads/claims and related clients
  • client: own portal and own claims

Authorization is enforced server-side using middleware and route-level checks.

Typical Flow: Lead to Claim

  1. Admin/supervisor/operator creates a lead.
  2. Products are attached to the lead.
  3. Lead is converted to client (/api/leads/:id/convert-to-client).
  4. Client receives portal access and product associations.
  5. Client submits claim (/api/claims).
  6. Admin/supervisor assigns claim (/api/claims/:id/assign).
  7. Team comments, uploads files, and updates status.

Reliability and Security Notes

  • DATABASE_URL and AUTH_SECRET are required at runtime.
  • Session-based auth avoids exposing bearer tokens in frontend code.
  • Sensitive credentials should never be committed.
  • Operators and clients are further restricted by ownership/assignment checks.