Skip to content

Core HR Platform – High-Level Architecture (Placeholder)

Purpose: Provide a concise system context for onboarding, threat modeling, and alignment. This placeholder will evolve into a richer multi-layer (Context -> Container -> Component) representation.

Context Diagram (Draft)!

C4Context
  title Core HR Platform – System Context
  Enterprise_Boundary(tnt, "Tenant Boundary") {
    Person(admin, "Tenant Admin", "Configures tenant, manages users & HR data")
    Person(employee, "Employee", "Consumes self-service HR features")
  }

  System(corehr, "Core HR Platform", "Multi-tenant HR & Core Services")
  System_Ext(idp, "Identity Provider", "OIDC/SAML Federation")
  System_Ext(payments, "Payment Gateway", "Subscription & Billing Events")
  System_Ext(docstore, "Object Storage", "Encrypted HR documents")
  System_Ext(email, "Email Service", "Transactional notifications")
  System_Ext(obs, "Observability Stack", "Logs, Metrics, Traces")
  System_Ext(analytics, "Analytics Warehouse", "Event ingestion & analysis")

  Rel(admin, corehr, "Configure + Admin APIs (HTTPS)")
  Rel(employee, corehr, "Self-service HR flows (HTTPS)")
  Rel(corehr, idp, "Federated auth (OIDC/SAML)")
  Rel(corehr, payments, "Subscription updates / billing webhooks")
  Rel(corehr, docstore, "Upload/Retrieve docs (signed URLs)")
  Rel(corehr, email, "Send transactional emails")
  Rel(corehr, obs, "Emit logs/metrics/traces")
  Rel(corehr, analytics, "Event stream (batch/stream)")

Key Cross-Cutting Concerns

  • Tenant Isolation: Enforced via repository predicates, cache key namespacing, scoped background workers.
  • Security: Federated authentication, least-privilege roles, no cross-tenant data leakage.
  • Observability: Structured logs + tracing per logging-tracing-guidelines.md; activation funnel KPIs.
  • Data Privacy: PII classification & retention (Recruitment, Performance reviews) pending.

Planned Expansions

  • Container Diagram: Break down API, Worker, Frontend SPA, Persistence, Messaging.
  • Component Diagram: Identity services, HR profile service, Leave engine, Document service.
  • Deployment Diagram: Multi-region active/passive + scaling groups + storage encryption.

Container Diagram (Draft)

C4Container
  title Core HR Platform – Container Diagram

  Person(admin, "Tenant Admin", "Configures tenant & HR settings")
  Person(employee, "Employee", "Self-service HR interactions")

  System_Boundary(core, "Core HR Platform") {
    Container(spa, "Web SPA", "TypeScript/React", "UI for admin & employee flows")
    Container(api, "API Service", "Java/Kotlin", "REST/GraphQL, auth, domain logic")
    Container(worker, "Async Workers", "Python", "Background tasks, enrichment, notifications")
    Container(cache, "Cache", "Redis", "Ephemeral session & computed lookups")
    ContainerQueue(queue, "Event/Task Broker", "Kafka", "Domain events & async jobs")
    ContainerDb(db, "Primary Database", "PostgreSQL", "Multi-tenant relational data (row isolation)")
    Container(docsvc, "Document Service", "Go", "Signed URL orchestration & antivirus scan")
    Container(obsagent, "Telemetry Sidecar", "OTel Collector", "Logs, metrics, traces export")
    Container(analyticsPipe, "Analytics Ingestion", "Flink", "Transforms events to warehouse schema")
  }

  Container_Ext(idp, "Identity Provider", "OIDC/SAML", "Federated auth")
  Container_Ext(payments, "Payment Gateway", "Stripe/etc", "Billing & subscription webhooks")
  Container_Ext(objstore, "Object Storage", "S3/Blob", "Encrypted HR documents")
  Container_Ext(email, "Email Service", "SES/SMTP", "Transactional notifications")
  Container_Ext(observability, "Observability Stack", "Elastic/Prom/Grafana", "Dashboards & alerting")
  Container_Ext(warehouse, "Analytics Warehouse", "BigQuery/Snowflake", "Event analytics & BI")

  Rel(admin, spa, "Uses (HTTPS)")
  Rel(employee, spa, "Uses (HTTPS)")
  Rel(spa, api, "Calls APIs")
  Rel(api, db, "CRUD (SQL)")
  Rel(api, cache, "Get/Set (TTL)")
  Rel(api, queue, "Publish domain events")
  Rel(worker, queue, "Consume events & tasks")
  Rel(worker, db, "Enrich/update records")
  Rel(worker, docsvc, "Request scan & URL issue")
  Rel(docsvc, objstore, "Store/retrieve documents")
  Rel(api, idp, "AuthN/AuthZ")
  Rel(api, payments, "Webhook handling / subscription ops")
  Rel(api, email, "Send transactional emails")
  Rel(queue, analyticsPipe, "Stream events")
  Rel(analyticsPipe, warehouse, "Load curated batches")
  Rel(obsagent, observability, "Emit telemetry")

Container Notes

3b. Component Diagram – API Internals (Draft)

C4Component
  title Core HR Platform – API Service Component Diagram

  Container(api, "API Service", "Java/Kotlin", "Entry point for synchronous domain logic")
  ContainerDb(db, "Primary Database", "PostgreSQL", "Multi-tenant relational store")
  ContainerQueue(queue, "Event Broker", "Kafka", "Domain events & async tasks")
  Container(cache, "Cache", "Redis", "Tenant-scoped ephemeral data")
  Container_Ext(idp, "Identity Provider", "OIDC/SAML", "External auth federation")
  Container_Ext(emailSvc, "Email Service", "SMTP/SES", "Transactional mail")
  Container_Ext(payments, "Payment Gateway", "Stripe/etc", "Billing webhooks")
  Container_Ext(docsvc, "Document Service", "Go", "File scan & signed URLs")
  Container_Ext(obs, "Observability", "OTel/Prom", "Telemetry sinks")

  Component(authCtrl, "Auth Controller", "REST", "Login, token refresh, MFA")
  Component(tenantCtrl, "Tenant Provisioning Controller", "REST", "Create/configure tenant")
  Component(empCtrl, "Employee Profile Controller", "REST", "CRUD employee profiles")
  Component(leaveCtrl, "Leave Management Controller", "REST", "Leave requests & approvals")
  Component(billingCtrl, "Billing Controller", "REST", "Plan management, subscription status")

  Component(identitySvc, "Identity Service", "Service", "User credentials & federated mapping")
  Component(tenantSvc, "Tenant Service", "Service", "Tenant lifecycle & isolation predicates")
  Component(employeeSvc, "Employee Service", "Service", "Profile aggregation & validation")
  Component(leaveEngine, "Leave Engine", "Service", "Accrual & balance calculations")
  Component(billingSvc, "Billing Integration", "Service", "Gateway events & proration logic")
  Component(docAdapter, "Document Adapter", "Service", "Abstraction for document service interactions")
  Component(notifyAdapter, "Notification Adapter", "Service", "Email dispatch & templating")
  Component(eventPublisher, "Event Publisher", "Service", "Serialize & publish domain events")
  Component(analyticsEmitter, "Analytics Emitter", "Service", "Fire analytics events to pipeline")
  Component(isolationGuard, "Isolation Guard", "Library", "Ensures tenant predicate applied")
  Component(permissionSvc, "Permission Service", "Service", "Role/permission evaluation")

  Rel(authCtrl, identitySvc, "Auth ops")
  Rel(tenantCtrl, tenantSvc, "Tenant provisioning")
  Rel(empCtrl, employeeSvc, "Profile ops")
  Rel(leaveCtrl, leaveEngine, "Leave ops")
  Rel(billingCtrl, billingSvc, "Billing ops")

  Rel(identitySvc, idp, "Federated auth")
  Rel(billingSvc, payments, "Webhook parse / API calls")
  Rel(docAdapter, docsvc, "Scan / signed URL")
  Rel(notifyAdapter, emailSvc, "Send emails")

  Rel(employeeSvc, db, "CRUD profiles")
  Rel(tenantSvc, db, "CRUD tenant config")
  Rel(identitySvc, db, "User & credential lookup")
  Rel(leaveEngine, db, "Accrual read/write")
  Rel(billingSvc, db, "Subscription state")
  Rel(permissionSvc, db, "Role matrix fetch")

  Rel(leaveEngine, cache, "Balance cache")
  Rel(employeeSvc, cache, "Profile hot cache")

  Rel(eventPublisher, queue, "Publish domain events")
  Rel(analyticsEmitter, queue, "Publish analytics events")

  Rel(eventPublisher, obs, "Trace spans")
  Rel(analyticsEmitter, obs, "Trace spans")
  Rel(authCtrl, isolationGuard, "Enforce tenant scope")
  Rel(empCtrl, isolationGuard, "Enforce tenant scope")
  Rel(leaveCtrl, isolationGuard, "Enforce tenant scope")
  Rel(billingCtrl, isolationGuard, "Enforce tenant scope")

Component Notes

  • IsolationGuard invoked early in controller pipeline to ensure queries include tenant predicates.
  • EventPublisher vs AnalyticsEmitter separation: domain events drive async workflows; analytics events feed BI pipeline.
  • PermissionService centralizes role evaluation to avoid scattered logic and ease future dynamic policy changes.
  • Document interactions abstracted to avoid coupling controller logic with scanning/signed URL details.
  • Caching selective (profiles, leave balances) to reduce DB load; invalidation triggered by domain events.

4. Open Items for Diagram Refinement

Item Status Target
Performance budget integration Added (referenced) Sprint 2 review
Event-driven architecture (activation pipeline) detail Pending Sprint 2 Mid
Explicit caching layer depiction Pending After perf tests
Async messaging (queue/topics) nodes Pending After design review
Zero trust / network segmentation notes Pending Security review

3c. Deployment Diagram (Draft)

%% C4 Deployment style diagram (simplified)
flowchart LR
  subgraph RegionA["Region A - Primary"]
    LB["Edge Load Balancer"]
    subgraph ASG_API["AutoScaling Group: API Service"]
      API1[("API Pod 1")]
      API2[("API Pod 2")]
    end
    subgraph ASG_WORKER["AutoScaling Group: Worker Service"]
      WRK1[("Worker 1")]
      WRK2[("Worker 2")]
    end
    Cache[("Redis Cluster")]
    DBPrimary[("PostgreSQL Primary")]
    Queue[("Kafka Cluster")]
    DocScan[("Document Scan Service")]
    Telemetry[("OTel Collector")]
  end

  subgraph RegionB["Region B - Passive / DR"]
    LBb["Edge LB (Passive)"]
    APIb[("Warm API Pod")]
    DBReplica[("PostgreSQL Replica")]
    CacheB[("Redis Replica")]
    QueueB[("Kafka Mirror")]
    TelemetryB[("OTel Collector")]
  end

  IdP[("Identity Provider")]
  Payments[("Payment Gateway")]
  ObjStore[("Object Storage")]
  Email[("Email Service")]
  Observability[("Central Observability Stack")]
  AnalyticsWH[("Analytics Warehouse")]

  IdP --> LB
  Payments --> LB
  LB --> API1
  LB --> API2
  API1 --> Cache
  API2 --> Cache
  API1 --> DBPrimary
  API2 --> DBPrimary
  API1 --> Queue
  API2 --> Queue
  WRK1 --> Queue
  WRK2 --> Queue
  WRK1 --> DBPrimary
  WRK2 --> DBPrimary
  WRK1 --> DocScan
  DocScan --> ObjStore
  API1 --> ObjStore
  API2 --> ObjStore
  API1 --> Email
  API2 --> Email
  Queue --> AnalyticsWH
  Telemetry --> Observability

  LBb --> APIb
  APIb --> DBReplica
  APIb --> CacheB
  APIb --> QueueB
  QueueB --> AnalyticsWH
  TelemetryB --> Observability

  DBPrimary --> DBReplica
  Cache --> CacheB
  Queue --> QueueB

Deployment Notes

  • Region A handles all live traffic; Region B kept warm for DR with async replication (DB, Cache, Kafka mirroring).
  • API autoscaling based on CPU + latency SLO breaches; workers scale on queue lag and document scan backlog size.
  • PostgreSQL replication async; RPO target < 5s, RTO target < 15m for region failover.
  • Redis replication configured with partial sync; session state minimized to reduce failover complexity.
  • Kafka MirrorMaker (or equivalent) maintains topic replication to Region B; consumer groups in passive region paused.
  • Telemetry collectors per region export to centralized observability stack; spans carry region attribute for differential analysis.
  • Object storage assumed cross-region durable (S3 multi-AZ); document scan service deployed only in primary region initially.
  • Failover Runbook: promote DBReplica to primary, switch DNS/LB routing, resume consumer groups, validate health checks.
  • Security Segmentation: Worker nodes isolated in private subnets; LB is the only public ingress; scanning service restricted egress.

5. How to Update

  1. Modify Mermaid block for context changes.
  2. Add new sections (Container/Component) as separate Mermaid blocks once stable.
  3. Validate diagram via tooling before commit.
  4. Reference new components in relevant docs (e.g., isolation strategy, runbook).

--- Placeholder created: refine post Sprint 1 mid-point when container boundaries stabilize.