zithtech/zithspace-be

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