Architecture Center

Phase 1

Authoritative architecture views. Source documents live in /docs/architecture; decision records are in /architecture/decisions.

System Context

Employees, managers, HR, payroll, finance, recruiters, candidates and platform staff interact with one suite that integrates with identity, banking, accounting and AI providers.

Candidates reach only the career portal surface
Platform staff never enter tenant data without just-in-time elevation
All external calls leave through the Integration Gateway

Mermaid

system-context.mmd

graph TD
  E[Employee] --> APP[RAGENTORA360]
  M[Manager] --> APP
  HR[HR / Recruiter] --> APP
  PAY[Payroll & Finance] --> APP
  CAND[Candidate] --> CP[Career Portal] --> APP
  SA[Platform Staff] --> ADM[Admin Portal] --> APP
  APP --> IDP[Enterprise IdP / SSO]
  APP --> BANK[Bank / Payment Provider]
  APP --> ERP[ERP / Accounting]
  APP --> AI[AI Gateway -> Approved Models]
  APP --> OBJ[Object Storage]

Container Architecture

Edge protection, then BFF, then authentication, tenant resolution, authorization and finally modules that reach data only through the tenant database router.

No module opens its own database connection
Authorization runs before any module code executes
Workers handle provisioning, payroll and payment jobs off the request path

Mermaid

container-architecture.mmd

graph TD
  U[Users] --> CDN[CDN / WAF]
  CDN --> WEB[Frontend Application]
  WEB --> BFF[API Gateway / BFF]
  BFF --> AUTH[Authentication]
  AUTH --> TCTX[Tenant Context Resolver]
  TCTX --> AZ[Authorization Engine]
  AZ --> MOD[Application Modules]
  MOD --> ROUTER[Tenant Database Router]
  ROUTER --> TDB[(Dedicated Organization Database)]
  MOD --> BUS[Event Bus] --> WRK[Workers]
  MOD --> AUD[Audit Service]

Control Plane

The platform database holds routing metadata only: tenant identity, subscription, status, region, database reference, key reference, feature configuration and platform administration data.

No employee, candidate, payroll, payslip, banking, document or finance rows
Never stores raw tenant database passwords — secret references only
Provisioning is idempotent and event-logged

Mermaid

control-plane.mmd

graph TD
  CP[(Platform Control DB)] --> REG[Tenant Registry]
  REG --> TA[Tenant A -> Tenant_A_DB]
  REG --> TB[Tenant B -> Tenant_B_DB]
  REG --> TC[Tenant C -> Tenant_C_DB]
  CP --> SUBS[Subscriptions & Feature Flags]
  CP --> PADM[Platform Administration & JIT Access]

Tenant Data Plane & Routing

Every organization owns a dedicated database. Tenant identity is derived from the session, resolved through the registry, and served from a per-tenant connection pool.

URL, header or resource tenant mismatch returns 403 and writes a security event
Clients can never supply a connection string or database reference
Per-tenant pool limits, pool TTL, migration version and health are tracked

Mermaid

tenant-data-plane.mmd

graph TD
  REQ[Authenticated Request] --> USR[User]
  USR --> MEM[Organization Membership]
  MEM --> TID[Tenant ID]
  TID --> REG[Tenant Registry]
  REG --> EP[Database Endpoint Ref]
  REG --> CRED[Credentials Reference]
  EP --> POOL[Per-Tenant Pool]
  POOL --> DB[(Dedicated DB)]
  TID -- mismatch --> DENY[403 + Security Audit Event]

IAM Architecture

OIDC/OAuth 2.1-compatible authentication with MFA, passkey-ready enrollment, refresh rotation, session inventory and revocation.

Password policy, lockout and brute-force protection are server enforced
Idle and absolute timeouts plus refresh-token rotation
Step-up authentication for high-risk actions

Mermaid

iam-architecture.mmd

graph TD
  L[Login] --> V[Server Verification]
  V --> MFA[MFA / Passkey]
  MFA --> S[Session Issued + Recorded]
  S --> R[Refresh Rotation]
  S --> IDLE[Idle Timeout]
  S --> ABS[Absolute Timeout]
  S --> REV[Revocation / Force Logout]
  V -- failure --> LOCK[Lockout + Audit]

Authorization Architecture

RBAC roles composed of resource.action.scope permissions, refined by ABAC scopes and field restrictions, evaluated in the backend on every request.

Scopes: SELF, DIRECT_REPORTS, TEAM, DEPARTMENT, LOCATION, PROJECT, LEGAL_ENTITY, ALL_TENANT, PLATFORM
Delegation boundary blocks granting authority the granter does not hold
Frontend visibility mirrors backend decisions and never replaces them

Mermaid

authorization-architecture.mmd

graph TD
  REQ[Request] --> PRIN[Principal + Tenant]
  PRIN --> ROLES[Role Assignments]
  ROLES --> PERMS[Permission Grants]
  PERMS --> SCOPE[Scope Evaluation ABAC]
  SCOPE --> FIELD[Field Restrictions]
  FIELD --> DEC{Allow?}
  DEC -- yes --> DATA[Scoped Data]
  DEC -- no --> D403[403 + Audit]

Event Architecture

Modules publish domain events to an internal bus so bounded contexts stay decoupled and can later become independent services.

Events carry tenant id, correlation id and actor
Workers own retries, DLQ and idempotency keys
Payroll and payment events never carry account numbers

Mermaid

event-architecture.mmd

graph LR
  REC[Recruitment] --> BUS((Event Bus))
  ONB[Onboarding] --> BUS
  PAYR[Payroll] --> BUS
  BUS --> NOTIF[Notifications]
  BUS --> AUDIT[Audit]
  BUS --> ANALYTICS[Analytics Pipeline]
  BUS --> DLQ[(Dead Letter Queue)]

AI Architecture

All AI traffic passes the AI Gateway: policy check, PII redaction, approved prompt template, approved model, output validation, human review.

No module calls an external model directly
Retrieval is authorized before context reaches the model
Consequential decisions always require a human approver

Mermaid

ai-architecture.mmd

graph TD
  MODULE[Module] --> GW[AI Gateway]
  GW --> POL[Policy Check]
  POL --> RED[PII Redaction]
  RED --> TPL[Prompt Template]
  TPL --> MODEL[Approved Model]
  MODEL --> VAL[Output Validation]
  VAL --> HUMAN[Human Review]

Security Architecture

Zero-trust posture: authenticate, resolve tenant, authorize, validate input, encrypt, audit — with maker-checker on money movement.

CSP, HSTS, secure headers, CSRF protection and rate limiting at the edge
KMS and secrets-manager abstractions; no secrets in source or frontend
Immutable append-only audit trail with sensitive-field masking

Mermaid

security-architecture.mmd

graph TD
  EDGE[WAF / Rate Limit] --> AUTHN[Authentication]
  AUTHN --> TEN[Tenant Isolation]
  TEN --> AUTHZ[Authorization]
  AUTHZ --> VALID[Input Validation]
  VALID --> CRYPT[Encryption + KMS]
  CRYPT --> AUDIT[Immutable Audit]
  AUDIT --> SOC[Security Monitoring]

Integration Architecture

One outbound gateway for identity, job boards, background checks, calendar, video, e-sign, banking, ERP, email, SMS and chat platforms.

Scoped credentials in a vault with rotation
Signed webhooks with replay protection and idempotency keys
Circuit breaker, retry policy and dead-letter handling

Mermaid

integration-architecture.mmd

graph TD
  MOD[Modules] --> IG[Integration Gateway]
  IG --> VAULT[Secret Vault]
  IG --> BANKS[Bank / Payments]
  IG --> ERP[ERP / Accounting]
  IG --> BGV[Background Verification]
  IG --> COMMS[Email / SMS / Chat]
  WH[Inbound Webhooks] --> SIG[Signature + Replay Check] --> MOD

Deployment Architecture

Development, test, staging and production are separate infrastructure with separate secrets, promoted only through the security pipeline.

No direct production deployment; protected branches
SBOM, artifact signing and image scanning before release
Per-region deployment for data residency

Mermaid

deployment-architecture.mmd

graph LR
  DEV[Development] --> TEST[Test]
  TEST --> STG[Staging]
  STG --> APPROVAL{Approval}
  APPROVAL --> PROD[Production]
  PROD --> OBS[Observability + SOC]

Disaster Recovery

Per-tenant PITR, encrypted snapshots, cross-region copies and restore validation with differentiated recovery objectives per domain.

Payroll and finance get the tightest RPO/RTO
Restores require privileged permission, reauthentication, reason and approval
Restore rehearsals are audited evidence

Mermaid

dr-architecture.mmd

graph TD
  TDB[(Tenant DB)] --> PITR[PITR]
  TDB --> SNAP[Daily Encrypted Snapshot]
  SNAP --> XREG[Cross-Region Copy]
  SNAP --> VALID[Restore Validation]
  VALID --> DRILL[DR Exercise Evidence]