# zithtech/zithspace-be architecture

> Architecture diagram of the GitHub repository zithtech/zithspace-be, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zithtech/zithspace-be
- Repository: https://github.com/zithtech/zithspace-be

## Overview

#### Purpose and runtime
Zithmi Backend V2 is a TypeScript/Express, multi-tenant business platform API. It combines project delivery, HR operations, payroll, recruitment, CRM/proposals, finance, documents, and client-portal capabilities in one server. `src/app.ts` is the application entry point; production compiled output is under `dist/app.js`. Docker deployment is defined by `Dockerfile` and `docker-compose.yml`.

#### HTTP composition and domain boundary
The application is route/controller-oriented for legacy and shared domains: route modules expose HTTP APIs and controllers implement request-facing orchestration. Key areas include authentication, projects/tickets/sprints, attendance/time tracking, invoices/transactions, employees, and document hub.
- `src/routes/auth.ts`
- `src/controllers/authController.ts`
- `src/routes/projects.ts`

Newer bounded modules use a clearer HTTP → controller → service → repository → dedicated database layout, rather than the flat controller set. Each module owns its routes, migrations, pool, validation, and domain services.
- `src/modules/payroll/http.ts`
- `src/modules/leave-v2/http.ts`
- `src/modules/opening-management/http.ts`

#### Tenant identity, authentication, and authorization
Tenant resolution is an upstream request boundary, supporting tenant context before protected domain handling. Authentication uses JWT utilities and middleware; authorization combines generic permission middleware with the RBAC module. PostgreSQL RLS is the intended final tenant-isolation layer, backed by tenant-aware Prisma/database configuration.
- `src/middleware/tenantContext.ts`
- `src/middleware/auth.ts`
- `src/middleware/permission.ts`
- `src/modules/rbac/rbac.service.ts`
- `src/config/database.ts`
- `prisma/schema.prisma`

Primary protected flow: request → tenant context → JWT/client-portal auth → permission or module gate → route/controller → persistence/service. Client-portal access is a separate security boundary.
- `src/middleware/clientPortalAuth.ts`
- `src/middleware/portalModuleGate.ts`
- `src/routes/clientPortal.ts`

#### Persistence and schema evolution
PostgreSQL is the core datastore. Prisma schema and migrations define the shared platform data model; additional SQL migration streams and module-local pools/schemas support newer or specialized subsystems. This means database ownership is mixed: shared Prisma-backed entities coexist with direct module repositories and dedicated pools.
- `prisma/schema.prisma`
- `prisma/migrations/0_baseline/migration.sql`
- `src/database/migrations/015_create_tenant_ai_settings.sql`
- `src/modules/payroll/db/pool.ts`
- `src/modules/leave-v2/db/migrations/001_init.sql`

#### Operational HR and finance workflows
HR functionality covers employee lifecycle, attendance, leave, onboarding/exit, and reimbursements. Payroll V2 is a discrete processing subsystem: employee assignments and structures feed pay-run calculation, approval/finalization, payslip generation, bank files, and reports.
- `src/controllers/attendanceController.ts`
- `src/modules/leave-v2/services/leaveRequest.service.ts`
- `src/modules/payroll/services/payRun.service.ts`
- `src/modules/payroll/services/payRunCalc.ts`
- `src/modules/payroll/services/payslipPdf.ts`

Reimbursement V2 similarly separates policies, claims, approvals, advances, budgets, and finance/reporting.
- `src/modules/reimbursement-v2/routes/index.ts`
- `src/modules/reimbursement-v2/services/claim.service.ts`
- `src/modules/reimbursement-v2/services/approval.service.ts`

#### Delivery, CRM, recruitment, and portals
Project-delivery flows center on clients, projects, tickets, QA, releases, timesheets, and sprint reporting; client portal APIs expose selected delivery artifacts externally. CRM/revenue features manage leads, proposals, bid assistance, templates, invoices, and mail. Recruitment spans requisitions/openings, applicants, approvals, postings, referrals, and candidate pipeline processing.
- `src/controllers/ticketController.ts`
- `src/controllers/sprintReportController.ts`
- `src/controllers/ProposalController.ts`
- `src/modules/opening-management/services/opening.service.ts`
- `src/modules/pipeline/services/candidateService.ts`

#### Async processing and integrations
Background work handles calendar/mail synchronization, scheduled mail, timer auto-pause, trash purging, leave accrual, and payslip generation. RabbitMQ is explicitly configured and queue/worker pairs isolate long-running synchronization and document-generation work from HTTP requests.
- `src/config/rabbitmq.ts`
- `src/workers/CalendarSyncWorker.ts`
- `src/workers/MailSyncWorker.ts`
- `src/modules/payroll/jobs/payslipWorker.ts`
- `src/modules/leave-v2/jobs/accrualWorker.ts`

External integration boundaries include Google, Microsoft, and Zoho calendar/mail providers; configurable AI providers; Redis/cache utilities; Cloudflare R2-style object storage; PDFs, email, sockets, and push notifications.
- `src/services/calendar/CalendarProviderFactory.ts`
- `src/services/mail/MailProviderFactory.ts`
- `src/services/ai/resolver.ts`
- `src/utils/r2Client.ts`
- `src/utils/redis.ts`

Main entry points: [`src/middleware/permission.ts`](https://github.com/zithtech/zithspace-be/blob/production/src/middleware/permission.ts) (Permissions & RBAC), [`prisma/schema.prisma`](https://github.com/zithtech/zithspace-be/blob/production/prisma/schema.prisma) (Shared PostgreSQL), [`src/routes/projects.ts`](https://github.com/zithtech/zithspace-be/blob/production/src/routes/projects.ts) (Legacy shared APIs), [`src/modules/payroll/http.ts`](https://github.com/zithtech/zithspace-be/blob/production/src/modules/payroll/http.ts) (Payroll V2)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP & Security"]
  node_app["Express application<br/>application entry<br/>[app.ts]"]
  node_tenant["Tenant context<br/>middleware<br/>[tenantContext.ts]"]
  node_auth["JWT authentication<br/>middleware<br/>[auth.ts]"]
  node_authorization["Permissions &amp; RBAC<br/>authorization<br/>[permission.ts]"]
  node_portal["Client portal boundary<br/>portal API<br/>[clientPortal.ts]"]
  node_legacy["Legacy shared APIs<br/>routes/controllers<br/>[projects.ts]"]
end

subgraph group_domains["Domain Modules"]
  node_payroll["Payroll V2<br/>bounded module<br/>[http.ts]"]
  node_leave["Leave V2<br/>bounded module<br/>[http.ts]"]
  node_reimbursement["Reimbursement V2<br/>bounded module<br/>[index.ts]"]
  node_recruitment["Recruitment modules<br/>bounded modules<br/>[http.ts]"]
  node_payrun["Pay-run calculation<br/>domain service<br/>[payRun.service.ts]"]
end

subgraph group_data["Data &amp; Async"]
  node_postgres[("Shared PostgreSQL<br/>database<br/>[schema.prisma]")]
  node_moduledb[("Module databases<br/>dedicated pools<br/>[pool.ts]")]
  node_migrations["Schema migrations<br/>SQL migrations<br/>[migration.sql]"]
  node_rabbitmq["RabbitMQ<br/>message broker<br/>[rabbitmq.ts]"]
  node_workers["Background workers"]
  node_payslipworker["Payslip worker<br/>payroll job<br/>[payslipWorker.ts]"]
end

subgraph group_integrations["External Services"]
  node_providers["Calendar &amp; mail providers<br/>external integrations"]
  node_platformservices["Platform services<br/>external services<br/>[resolver.ts]"]
end

node_app -->|"all requests"| node_tenant
node_tenant -->|"protected API"| node_auth
node_auth -->|"authenticated principal"| node_authorization
node_authorization -->|"authorized request"| node_legacy
node_authorization -->|"module access"| node_payroll
node_authorization -->|"module access"| node_leave
node_authorization -->|"module access"| node_reimbursement
node_authorization -->|"module access"| node_recruitment
node_app -->|"portal requests"| node_portal
node_legacy -->|"shared persistence"| node_postgres
node_payroll -->|"orchestrates"| node_payrun
node_payrun -->|"payroll data"| node_moduledb
node_leave -->|"module persistence"| node_moduledb
node_reimbursement -->|"platform persistence"| node_postgres
node_recruitment -->|"platform persistence"| node_postgres
node_migrations -->|"evolves shared schema"| node_postgres
node_payrun -->|"queues payslips"| node_rabbitmq
node_rabbitmq -->|"payslip jobs"| node_payslipworker
node_rabbitmq -->|"async jobs"| node_workers
node_workers -->|"calendar and mail sync"| node_providers
node_legacy -->|"uses platform integrations"| node_platformservices
node_payroll -->|"PDF and notifications"| node_platformservices

click node_app "https://github.com/zithtech/zithspace-be/blob/production/src/app.ts"
click node_tenant "https://github.com/zithtech/zithspace-be/blob/production/src/middleware/tenantContext.ts"
click node_auth "https://github.com/zithtech/zithspace-be/blob/production/src/middleware/auth.ts"
click node_authorization "https://github.com/zithtech/zithspace-be/blob/production/src/middleware/permission.ts"
click node_portal "https://github.com/zithtech/zithspace-be/blob/production/src/routes/clientPortal.ts"
click node_legacy "https://github.com/zithtech/zithspace-be/blob/production/src/routes/projects.ts"
click node_payroll "https://github.com/zithtech/zithspace-be/blob/production/src/modules/payroll/http.ts"
click node_leave "https://github.com/zithtech/zithspace-be/blob/production/src/modules/leave-v2/http.ts"
click node_reimbursement "https://github.com/zithtech/zithspace-be/blob/production/src/modules/reimbursement-v2/routes/index.ts"
click node_recruitment "https://github.com/zithtech/zithspace-be/blob/production/src/modules/opening-management/http.ts"
click node_payrun "https://github.com/zithtech/zithspace-be/blob/production/src/modules/payroll/services/payRun.service.ts"
click node_postgres "https://github.com/zithtech/zithspace-be/blob/production/prisma/schema.prisma"
click node_moduledb "https://github.com/zithtech/zithspace-be/blob/production/src/modules/payroll/db/pool.ts"
click node_migrations "https://github.com/zithtech/zithspace-be/blob/production/prisma/migrations/0_baseline/migration.sql"
click node_rabbitmq "https://github.com/zithtech/zithspace-be/blob/production/src/config/rabbitmq.ts"
click node_workers "https://github.com/zithtech/zithspace-be/blob/production/src/workers/CalendarSyncWorker.ts"
click node_payslipworker "https://github.com/zithtech/zithspace-be/blob/production/src/modules/payroll/jobs/payslipWorker.ts"
click node_providers "https://github.com/zithtech/zithspace-be/blob/production/src/services/calendar/CalendarProviderFactory.ts"
click node_platformservices "https://github.com/zithtech/zithspace-be/blob/production/src/services/ai/resolver.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_tenant,node_auth,node_authorization,node_portal,node_legacy toneBlue
class node_payroll,node_leave,node_reimbursement,node_recruitment,node_payrun toneAmber
class node_postgres,node_moduledb,node_migrations,node_rabbitmq,node_workers,node_payslipworker toneMint
class node_providers,node_platformservices toneRose
```

## Components

### HTTP & Security

- [Express application](https://github.com/zithtech/zithspace-be/blob/production/src/app.ts): application entry · Composes the multi-tenant API. · `src/app.ts`
- [Tenant context](https://github.com/zithtech/zithspace-be/blob/production/src/middleware/tenantContext.ts): middleware · Establishes tenant identity before protected handling. · `src/middleware/tenantContext.ts`
- [JWT authentication](https://github.com/zithtech/zithspace-be/blob/production/src/middleware/auth.ts): middleware · `src/middleware/auth.ts`
- [Permissions & RBAC](https://github.com/zithtech/zithspace-be/blob/production/src/middleware/permission.ts): authorization · `src/middleware/permission.ts`
- [Client portal boundary](https://github.com/zithtech/zithspace-be/blob/production/src/routes/clientPortal.ts): portal API · Separate authentication and module-access boundary. · `src/routes/clientPortal.ts`
- [Legacy shared APIs](https://github.com/zithtech/zithspace-be/blob/production/src/routes/projects.ts): routes/controllers · Route/controller APIs for auth, projects, attendance, finance, and documents. · `src/routes/projects.ts`

### Domain Modules

- [Payroll V2](https://github.com/zithtech/zithspace-be/blob/production/src/modules/payroll/http.ts): bounded module · Owns HTTP, services, repository, migrations, and pool. · `src/modules/payroll/http.ts`
- [Leave V2](https://github.com/zithtech/zithspace-be/blob/production/src/modules/leave-v2/http.ts): bounded module · Owns leave requests and accrual processing. · `src/modules/leave-v2/http.ts`
- [Reimbursement V2](https://github.com/zithtech/zithspace-be/blob/production/src/modules/reimbursement-v2/routes/index.ts): bounded module · Claims, approvals, advances, budgets, and reporting. · `src/modules/reimbursement-v2/routes/index.ts`
- [Recruitment modules](https://github.com/zithtech/zithspace-be/blob/production/src/modules/opening-management/http.ts): bounded modules · Openings and candidate pipeline processing. · `src/modules/opening-management/http.ts`
- [Pay-run calculation](https://github.com/zithtech/zithspace-be/blob/production/src/modules/payroll/services/payRun.service.ts): domain service · Calculates, approves, and finalizes pay runs. · `src/modules/payroll/services/payRun.service.ts`

### Data & Async

- [Shared PostgreSQL](https://github.com/zithtech/zithspace-be/blob/production/prisma/schema.prisma): database · Shared platform model with tenant RLS intent. · `prisma/schema.prisma`
- [Module databases](https://github.com/zithtech/zithspace-be/blob/production/src/modules/payroll/db/pool.ts): dedicated pools · Direct repositories and specialized module schemas coexist with Prisma. · `src/modules/payroll/db/pool.ts`
- [Schema migrations](https://github.com/zithtech/zithspace-be/blob/production/prisma/migrations/0_baseline/migration.sql): SQL migrations · Shared and module-local schema evolution streams. · `prisma/migrations/0_baseline/migration.sql`
- [RabbitMQ](https://github.com/zithtech/zithspace-be/blob/production/src/config/rabbitmq.ts): message broker · Queues long-running synchronization and document jobs. · `src/config/rabbitmq.ts`
- [Background workers](https://github.com/zithtech/zithspace-be/blob/production/src/workers/CalendarSyncWorker.ts): workers · Calendar/mail sync, leave accrual, and scheduled maintenance. · `src/workers/CalendarSyncWorker.ts`
- [Payslip worker](https://github.com/zithtech/zithspace-be/blob/production/src/modules/payroll/jobs/payslipWorker.ts): payroll job · Generates payslips asynchronously. · `src/modules/payroll/jobs/payslipWorker.ts`

### External Services

- [Calendar & mail providers](https://github.com/zithtech/zithspace-be/blob/production/src/services/calendar/CalendarProviderFactory.ts): external integrations · Google, Microsoft, and Zoho provider boundary. · `src/services/calendar/CalendarProviderFactory.ts`
- [Platform services](https://github.com/zithtech/zithspace-be/blob/production/src/services/ai/resolver.ts): external services · AI, Redis cache, object storage, email, sockets, and push. · `src/services/ai/resolver.ts`

## Connections

- Express application → Tenant context: all requests
- Tenant context → JWT authentication: protected API
- JWT authentication → Permissions & RBAC: authenticated principal
- Permissions & RBAC → Legacy shared APIs: authorized request
- Permissions & RBAC → Payroll V2: module access
- Permissions & RBAC → Leave V2: module access
- Permissions & RBAC → Reimbursement V2: module access
- Permissions & RBAC → Recruitment modules: module access
- Express application → Client portal boundary: portal requests
- Legacy shared APIs → Shared PostgreSQL: shared persistence
- Payroll V2 → Pay-run calculation: orchestrates
- Pay-run calculation → Module databases: payroll data
- Leave V2 → Module databases: module persistence
- Reimbursement V2 → Shared PostgreSQL: platform persistence
- Recruitment modules → Shared PostgreSQL: platform persistence
- Schema migrations → Shared PostgreSQL: evolves shared schema
- Pay-run calculation → RabbitMQ: queues payslips
- RabbitMQ → Payslip worker: payslip jobs
- RabbitMQ → Background workers: async jobs
- Background workers → Calendar & mail providers: calendar and mail sync
- Legacy shared APIs → Platform services: uses platform integrations
- Payroll V2 → Platform services: PDF and notifications