Protected Page

Enter password to view the HorixOS main blueprint page.

HorixOS — Complete Business & Technical Blueprint

Consolidated presentation document built from all requirement files: macro architecture, workflow, SaaS services, monorepo directory design, RBAC permission matrix, and API/route catalog — all in a light-theme, structured format.

Multi-tenant SaaS AI-Powered Recruitment OS Event-Driven Analytics Communication Intelligence Stripe + OAuth + RBAC
7
Primary Architecture Blocks
16
RBAC Permission Domains
16
API Module Groups
3
Core User Roles + Platform Admin
3
Logical DB Schemas
View Business Flow Jump to RBAC Jump to API Catalog Open Layman Diagrams

1) Macro Architecture

Platform Control Plane

Tenant registry, subscription/billing, plan enforcement, usage metering, Redis rate limiting, feature flags, tenant provisioning, telemetry, internal admin.

API Gateway

Subdomain resolver, JWT auth middleware, tenant resolver, plan validator, rate limiter, request router.

Product Execution Plane

Data acquisition, ATS core, matching engine, workforce intelligence, compliance manager, supervised AI execution.

Communication Intelligence Layer

VOIP, call recording, STT, NLP/sentiment, talk/listen ratio, compliance phrase detection, email intent analysis, engagement scoring.

Intelligence & Data Plane

Event bus backbone, real-time analytics, ROI engine, behavioral/burnout models, vector database, AI services, audit & observability.

Data Storage Layer

PostgreSQL (platform/product/analytics), object storage (calls/resumes/docs), Redis (queues/rate/session), vector DB (pgvector or Pinecone).

Three-Plane System Model (Textual)

Platform Control Plane
        ↓
     API Gateway
        ↓
Product Execution + Communication Intelligence + Intelligence/Data Plane

Critical Event Types

candidate_created

job_posted

call_completed

email_sent

pipeline_stage_changed

ai_suggestion_generated

recruiter_session_started

compliance_flag_detected

Tenant Isolation & Economic Governance

  1. Subdomain resolution
  2. Tenant lookup
  3. Subscription validation
  4. Rate limit check
  5. Usage quota validation
  6. Execution

2) SaaS Service Architecture

Users (Owner | Manager | Recruiter)
  → Frontend (Next.js)
  → API Gateway
  → Auth + Tenant + Plan + Rate Guard
  → Core Services
  → Queues/Workers (heavy tasks)
  → DB + Event Bus
  → Analytics + Dashboard updates

Core Backend Service Layer

Auth Service

JWT + OAuth (Google/Microsoft), request validation.

Tenant Service

Multi-tenant isolation and provisioning.

Billing Service

Stripe checkout, subscriptions, invoices, portal, usage metering.

ATS Service

Jobs, candidates, pipeline, placements, compliance.

Scraping Service

Playwright worker + parsing + AI structuring into ATS.

Matching Engine

Rule filtering + pgvector cosine similarity + weighted rank.

Communication Service

Twilio/VOIP + Email provider + transcript/email intelligence.

AI Adapter

OpenAI/Gemini/Anthropic for parsing, generation, analysis, embeddings.

Workforce Analytics

Sessions, activity, productivity, burnout indicators.

Usage Metering

AI tokens, call minutes, storage, API and seats.

Event Bus Service

Redis streams consumers for analytics, ROI, notifications, billing.

Authentication Flow
Login → Auth Service → JWT/OAuth
JWT in HTTP-only cookie
Every request validated at gateway
Billing Flow (Stripe)
Owner selects plan → Checkout session
Payment → Webhook → subscription update
Plan enforcement + metering active
Call Intelligence
Recruiter call → Twilio
Recording stored → Webhook
Transcription queue → AI analysis
Sentiment/engagement stored → Event emitted
Email Intelligence
Email send/receive → provider webhook
Thread stored → AI context extraction
Intent + engagement score updated

Service Options Table

FunctionPrimaryAlternatives
HostingOracle / AWSGCP / Fly.io
FrontendVercel / Next.jsCloudflare Pages
BackendNestJSFastify / Express
DatabasePostgresMySQL
VectorpgvectorPinecone
AIOpenAIGemini / Anthropic
VOIPTwilioPlivo / Vonage
EmailResendSendGrid / SES
PaymentsStripePaddle / Razorpay
QueueRedisKafka / SQS
AuthJWTClerk / Auth0

Upgrade Path After Revenue

3) Business Workflow (End-to-End)

Agency signs up → Tenant provisioned → Owner configures org
→ Jobs created → Data ingestion/sourcing → Matching ranks candidates
→ Recruiters communicate → Calls & emails analyzed
→ Candidate moves in pipeline → Placement completed
→ Performance & ROI tracked → AI optimizes decisions

Operational Timeline

  1. Tenant onboarding: signup, subdomain, plan selection, tenant provisioning, owner creation, quota setup.
  2. Org setup: managers/recruiters added, hierarchy and weights configured, email/VOIP/scraping connections.
  3. Execution loop: job creation, sourcing, matching, communication, stage movement, placement.
  4. Intelligence loop: transcript/email analysis, engagement scoring, performance and burnout insights.
  5. Business loop: usage metering, overage calculations, invoices, upgrade prompts, suspension logic when needed.

Role Workflows

Owner
  • Dashboard: total jobs, active candidates, productivity, revenue/recruiter, cost/placement, AI savings, utilization, burnout.
  • Actions: create managers, upgrade plan, adjust quotas, configure compliance and feature controls, review ROI.
Manager
  • Dashboard: activity score, open jobs, pipeline velocity, call/email effectiveness, conversion rate, burnout, capacity.
  • Actions: assign/reassign work, review transcripts, coaching feedback, trigger AI shortlist, monitor compliance alerts.
Recruiter
  • Daily flow: login → dashboard → AI suggestions → open tasks → pipeline.
  • Execution: create jobs, source candidates, run matches, call/email outreach, move candidates across stages.

Communication + Candidate Lifecycle

Call Workflow
Call initiate → record → store → transcribe
→ AI transcript analysis → engagement score
→ metrics saved → event emitted → dashboard update
Email Workflow
Email sent via platform → thread stored
→ intent extraction → engagement scoring
→ response tracking → pipeline suggestions
Candidate Lifecycle
Profile created → Enriched/classified → Matched → Contacted → Screened
→ Interview → Offer → Placement → Post-placement tracking

AI Feedback Loop

Recruiter action → event generated → event bus storage
→ AI learns patterns → predictive model updated
→ future recommendations improved

Examples: recruiter-close-rate learning, burnout trend detection, matching-weight adjustment, drop-off prediction.

4) Implementation Directory Blueprint

Recommended monorepo: pnpm + Turborepo (or Nx).

Monorepo Structure

horixos/
├── apps/
│   ├── web/       # Next.js frontend
│   ├── api/       # NestJS backend
│   └── workers/   # background worker processes
├── packages/
│   ├── shared-types/
│   ├── shared-config/
│   ├── shared-utils/
│   └── ui-kit/
├── infra/
│   ├── docker/
│   ├── nginx/
│   ├── terraform/
│   └── scripts/
├── docs/
├── .env.example
├── package.json
└── turbo.json
Frontend Structure (apps/web) 
web/
├── app/
│   ├── (marketing)/
│   ├── (auth)/login | register | oauth-callback
│   ├── (dashboard)/owner | manager | recruiter | analytics | billing | settings
│   ├── jobs/ | candidates/ | pipeline/
│   ├── communication/calls | emails | transcripts
│   ├── admin/
│   └── layout.tsx
├── components/ui | dashboard | pipeline | communication | charts | billing
├── hooks/
├── lib/api-client.ts | auth.ts | tenant.ts | stripe.ts
├── middleware.ts  # subdomain -> tenant resolver
└── styles/
Backend Structure (apps/api) 
src/
├── core/ (database, redis, storage, event-bus, logging, guards, interceptors, middlewares)
├── auth/
├── platform/ (tenants, billing, usage, rate-limit, feature-flags, admin)
├── ats/ (jobs, candidates, pipeline, placements, compliance)
├── scraping/ (controllers, services, workers, parsers, dto)
├── matching/ (scoring, vector, services)
├── communication/
│   ├── voip/ (twilio.service.ts, call.controller.ts, call.webhook.ts)
│   ├── email/ (smtp.service.ts, email.webhook.ts)
│   ├── transcription/ (transcription.worker.ts, whisper.adapter.ts)
│   └── nlp/ (sentiment, engagement, compliance services)
├── ai/ (providers, resume-parser, jd-generator, transcript-analysis, embeddings, recommendations)
├── workforce/ (sessions, activity, productivity)
├── analytics/ (aggregations, roi, dashboards, reports)
└── events/ (publishers, consumers, event-types.ts)

Workers, Database, Queue, Auth, Billing, AI Adapter

Workers

scraping.worker.ts, transcription.worker.ts, ai.worker.ts, analytics.worker.ts, billing.worker.ts, worker.module.ts.

Database Schemas

platform.* (tenants, subscriptions, usage_logs, feature_flags), product.* (users, jobs, candidates, applications, pipeline_stages, calls, transcripts, emails), analytics.* (recruiter_metrics, roi_metrics, engagement_scores, burnout_index).

Queue Structure

scraping.queue.ts, transcription.queue.ts, ai.queue.ts, analytics.queue.ts, billing.queue.ts.

Auth Flow Files

jwt.strategy.ts, google.strategy.ts, microsoft.strategy.ts, auth.controller.ts, auth.service.ts.

Billing Files

stripe.service.ts, webhook.controller.ts, subscription.service.ts, metering.service.ts.

AI Adapter Pattern

ai.interface.ts, openai.provider.ts, gemini.provider.ts for provider switching per tenant/plan.

Clean Separation Principle

Product Plane

ats, scraping, matching, communication, workforce.

Platform Plane

billing, usage, tenant, rate-limit.

Intelligence Plane

ai, analytics, events.

✔ Multi-tenant SaaS ready ✔ Stripe billing integrated ✔ OAuth login ✔ AI provider abstraction ✔ Queue-based background processing ✔ Event-driven analytics ✔ Clean modular boundaries

5) RBAC Permission Matrix (Complete)

Roles: Platform Admin (internal), Owner (tenant), Manager (team), Recruiter (operational).

✅ Allowed 🟡 Limited / Scoped ❌ Not Allowed

Role Definitions

Platform Admin

Cross-tenant management, system health, global billing oversight; no recruitment execution.

Owner

Full tenant access including billing, team management, strategic analytics, feature control.

Manager

Team oversight, supervision, performance/compliance monitoring; no billing control.

Recruiter

ATS execution, communication, AI-assisted tasks; no team/billing control.

Permission Categories

Authentication, Tenant/Platform, Billing, User Management, ATS, Scraping, Matching, Communication, AI Usage, Workforce Analytics, ROI Analytics, Compliance, System Flags, Notifications, Event Audit.

1) Auth & Profile
ActionPlatform AdminOwnerManagerRecruiter
Login✅✅✅✅
Update own profile✅✅✅✅
Reset own password✅✅✅✅
2) Tenant Management
ActionPlatform AdminOwnerManagerRecruiter
View tenant info✅ (all tenants)✅🟡 (view only)❌
Update tenant config✅✅❌❌
Suspend tenant✅❌❌❌
View feature flags✅✅🟡❌
3) Billing (Stripe)
ActionPlatform AdminOwnerManagerRecruiter
View subscription✅✅❌❌
Upgrade/downgrade plan❌✅❌❌
View invoices✅✅❌❌
Access billing portal❌✅❌❌
View usage metering✅✅🟡 (team level)❌
4) User Management
ActionPlatform AdminOwnerManagerRecruiter
Invite user❌✅🟡 (recruiter only)❌
Change role❌✅❌❌
Remove user❌✅❌❌
View team❌✅✅❌
5) ATS - Jobs
ActionPlatform AdminOwnerManagerRecruiter
Create job❌✅✅✅
Edit job❌✅✅🟡 (own jobs only)
Close job❌✅✅❌
Delete job❌✅❌❌
6) ATS - Candidates
ActionPlatform AdminOwnerManagerRecruiter
Create candidate❌✅✅✅
Edit candidate❌✅✅🟡 (assigned only)
Delete candidate❌✅❌❌
Upload resume❌✅✅✅
7) Pipeline
ActionPlatform AdminOwnerManagerRecruiter
Move candidate stage❌✅✅✅
Create stage❌✅❌❌
Edit stage❌✅❌❌
8) Scraping
ActionPlatform AdminOwnerManagerRecruiter
Create scrape job❌✅🟡 (if enabled)❌
Cancel scrape job❌✅❌❌
View scrape results❌✅✅🟡

Scraping is often plan-restricted.

9) Matching
ActionPlatform AdminOwnerManagerRecruiter
Run matching❌✅✅✅
Adjust matching weights❌✅❌❌
View match explanation❌✅✅✅
10) Communication - Calls
ActionPlatform AdminOwnerManagerRecruiter
Initiate call❌✅✅✅
View all call logs❌✅✅❌
View own call logs❌❌❌✅
Delete recording❌✅❌❌
View transcript analysis❌✅✅🟡 (own only)
11) Communication - Email
ActionPlatform AdminOwnerManagerRecruiter
Send email❌✅✅✅
View all threads❌✅✅❌
View own threads❌❌❌✅
View AI email insights❌✅✅🟡
12) AI Usage
ActionPlatform AdminOwnerManagerRecruiter
Use AI tools❌✅✅✅
View AI token usage✅✅🟡❌
Override AI limits❌✅❌❌
13) Workforce Analytics
ActionPlatform AdminOwnerManagerRecruiter
View personal productivity❌❌❌✅
View team productivity❌❌✅❌
View company productivity❌✅❌❌
View burnout indicators❌✅✅❌
14) ROI & Business Analytics
ActionPlatform AdminOwnerManagerRecruiter
View ROI dashboard❌✅❌❌
View revenue impact❌✅❌❌
View AI efficiency gains❌✅🟡❌
15) Compliance
ActionPlatform AdminOwnerManagerRecruiter
Set compliance rules❌✅❌❌
View compliance flags❌✅✅🟡
Edit compliance records❌✅❌❌
16) Admin (Platform Only)
ActionPlatform AdminOwnerManagerRecruiter
View all tenants✅❌❌❌
Suspend tenant✅❌❌❌
View global usage✅❌❌❌
System health✅❌❌❌

Scoping Rules

Recruiter Scope

Own jobs, assigned candidates, own calls/emails.

Manager Scope

Team members and assigned recruiters; no billing.

Owner Scope

Entire tenant, billing access, feature controls.

Platform Admin Scope

Cross-tenant platform controls, no operational recruitment actions.

Implementation Strategy

Use NestJS Role Guard + Permission Guard + Resource Scope Guard + Plan Guard
Example:
@Roles(Role.Owner, Role.Manager)
@Permissions(Permission.VIEW_TEAM_ANALYTICS)

Advanced Enterprise Additions

6) API & Route Catalog (Complete)

Base URL: https://{tenant}.horixos.com/api | Admin base: https://admin.horixos.com/api | Auth: JWT cookie or Bearer token | Tenant-scoped endpoints | RBAC via guards.

1) Auth Module — /api/auth
MethodEndpointUse Case
POST/auth/registerRegister tenant owner + create tenant
POST/auth/loginEmail/password login
POST/auth/logoutInvalidate refresh token
POST/auth/refreshRefresh JWT
GET/auth/meCurrent user profile
GET/auth/googleGoogle OAuth redirect
GET/auth/google/callbackGoogle OAuth callback
GET/auth/microsoftMicrosoft OAuth login
GET/auth/microsoft/callbackMicrosoft OAuth callback
2) Tenant & Platform — /api/platform
MethodEndpointUse Case
GET/platform/tenantGet tenant info
PATCH/platform/tenantUpdate tenant config
GET/platform/tenant/usageCurrent usage stats
GET/platform/tenant/featuresFeature flags
3) Billing (Stripe) — /api/platform/billing
MethodEndpointUse Case
POST/billing/checkout-sessionCreate Stripe checkout
GET/billing/subscriptionSubscription details
POST/billing/portalStripe customer portal
POST/billing/webhookStripe webhook handler
GET/billing/invoicesList invoices
GET/billing/usageMetered usage breakdown

Supports plan upgrades, overages, seat billing, AI token metering.

4) User Management — /api/users
MethodEndpointUse Case
POST/usersInvite user
GET/usersList users
GET/users/:idGet user
PATCH/users/:idUpdate role
DELETE/users/:idRemove user
POST/users/:id/reset-passwordReset password
5) ATS Jobs — /api/jobs
MethodEndpointUse Case
POST/jobsCreate job
GET/jobsList jobs
GET/jobs/:idJob details
PATCH/jobs/:idUpdate job
DELETE/jobs/:idArchive job
POST/jobs/:id/closeClose job
POST/jobs/:id/matchRun matching engine
6) ATS Candidates — /api/candidates
MethodEndpointUse Case
POST/candidatesCreate candidate
GET/candidatesList candidates
GET/candidates/:idCandidate details
PATCH/candidates/:idUpdate profile
DELETE/candidates/:idArchive
POST/candidates/:id/upload-resumeUpload resume
GET/candidates/:id/matchesMatching jobs
7) Pipeline — /api/pipeline
MethodEndpointUse Case
GET/pipeline/:jobIdGet job pipeline
POST/pipeline/moveMove candidate stage
GET/pipeline/stagesList stages
PATCH/pipeline/stages/:idEdit stage
POST/pipeline/stagesCreate stage
8) Scraping — /api/scraping
MethodEndpointUse Case
POST/scraping/jobCreate scrape job
GET/scraping/jobsList scrape jobs
GET/scraping/jobs/:idStatus
DELETE/scraping/jobs/:idCancel
POST/scraping/parseParse raw data
9) Matching — /api/matching
MethodEndpointUse Case
POST/matching/job/:jobIdRank candidates
POST/matching/candidate/:idFind jobs
POST/matching/weightsAdjust scoring weights
GET/matching/explain/:matchIdAI explanation
10) Communication Calls — /api/communication/calls
MethodEndpointUse Case
POST/calls/initiateStart call
GET/callsList calls
GET/calls/:idCall details
POST/calls/webhookTwilio webhook
GET/calls/:id/transcriptTranscript
GET/calls/:id/analysisAI sentiment
DELETE/calls/:idDelete recording
11) Communication Email — /api/communication/email
MethodEndpointUse Case
POST/email/sendSend email
GET/email/threadsList threads
GET/email/thread/:idThread details
POST/email/webhookSMTP webhook
GET/email/:id/analysisAI insights
12) AI Module — /api/ai
MethodEndpointUse Case
POST/ai/parse-resumeAI resume parsing
POST/ai/generate-jdGenerate job description
POST/ai/analyze-transcriptTranscript NLP
POST/ai/suggest-tasksRecruiter suggestions
GET/ai/usageToken usage
POST/ai/testDebug endpoint
13) Workforce Analytics — /api/workforce
MethodEndpointUse Case
POST/workforce/session/startStart session
POST/workforce/session/endEnd session
GET/workforce/productivityRecruiter metrics
GET/workforce/team-metricsManager view
GET/workforce/burnoutBurnout indicators
14) Analytics & ROI — /api/analytics
MethodEndpointUse Case
GET/analytics/dashboardOwner dashboard
GET/analytics/conversionPipeline conversion
GET/analytics/roiRevenue impact
GET/analytics/ai-impactAI productivity gain
GET/analytics/capacityTeam capacity
15) Notifications — /api/notifications
MethodEndpointUse Case
GET/notificationsList notifications
PATCH/notifications/:id/readMark read
DELETE/notifications/:idDelete notification
16) Admin (Platform Only) — admin.horixos.com/api/admin
MethodEndpointUse Case
GET/admin/tenantsList tenants
GET/admin/tenant/:idTenant details
PATCH/admin/tenant/:id/suspendSuspend tenant
GET/admin/system/healthInfrastructure health
GET/admin/usage/globalGlobal usage metrics
Internal Event Endpoints — /api/events
MethodEndpointUse Case
POST/events/publishEmit event
GET/events/logsDebug logs

Typically internal-only endpoints.

End-to-End Request Flow

Client → Frontend → API Gateway
→ Auth Guard → Tenant Guard → Rate Limit Guard
→ Controller → Service → Queue (if heavy) → Worker
→ External API → DB → Event Bus → Analytics update

API Design Principles

7) Final System Identity

HorixOS is a vertically integrated, AI-powered healthcare recruitment infrastructure operating system combining ATS workflows, autonomous data ingestion, communication intelligence, workforce analytics, billing governance, and tenant-aware SaaS controls into one unified cloud platform.

✔ Multi-tenant ✔ Event-driven ✔ AI-augmented ✔ Communication-intelligent ✔ Behavior-aware ✔ Economically governed ✔ Compliance-ready ✔ Scalable architecture path
↑ Top