Campus Placement Platform — Spec Index

Multitenant B2B SaaS for campus recruitment. Think Superset, built for Indian universities.

How to use this spec

Each file is self-contained and written to be fed directly to an AI coding agent. Start with the architecture overview, then pick the service you're building.

Files

Architecture & overview

File What it covers
README.md This file — index and orientation
architecture.md System design, multitenancy pattern, all services, data flow

Per-service specs (feed these to agents)

File Service
apps/api-gateway.md TypeScript — entry point, tenant resolution, JWT, routing
apps/core-api.md TypeScript — main business logic monolith
apps/tenant-web.md TypeScript / Next.js — student + admin frontend
apps/notification-service.md TypeScript — email/push/webhook worker
apps/ai-worker.md Python — LLM tasks, resume AI

Infrastructure

File What it covers
infra/overview.md All running processes, ports, docker-compose, k8s layout
infra/database.md Full Postgres schema, all tables, indexes, RLS
infra/auth.md OAuth, OTP, JWT, refresh token, revocation
infra/queue.md BullMQ setup, job types, retry strategy

Product

File What it covers
product/user-stories.md All roles, all stories, acceptance criteria
product/views-ui.md Every screen, what data it shows, interactions
product/rbac.md Roles, permissions matrix, API key scopes
product/segmentation.md Query builder spec, all operators, usage across product
product/resume.md Resume JSON schema, verification flow, AI variants

Stack decisions (locked)

  • All services: TypeScript (Node 20, Fastify)
  • AI worker only: Python 3.11 (FastAPI + Celery)
  • Frontend: Next.js 14 (App Router, TypeScript)
  • ORM: Prisma (core-api), raw SQL for read-heavy queries
  • Database: Postgres 16 (shared schema multitenant)
  • Cache / sessions: Redis 7
  • Queue: BullMQ (backed by Redis, no separate broker)
  • Object storage: S3-compatible (AWS S3 or Cloudflare R2)
  • Search: Postgres full-text + pg_trgm (no Meilisearch until needed)
  • Container orchestration: Kubernetes (local: docker-compose)
  • CI/CD: GitHub Actions → ECR → Helm

Monorepo layout

/
├── apps/
│   ├── api-gateway/         # Fastify, TS
│   ├── core-api/            # Fastify, TS, Prisma
│   ├── tenant-web/          # Next.js 14, TS
│   ├── notification-service/ # Node worker, TS
│   └── ai-worker/           # FastAPI, Python
├── packages/
│   ├── types/               # Shared TS types + Zod schemas
│   ├── db/                  # Prisma schema + migrations
│   └── queue/               # BullMQ job definitions + types
├── infra/
│   ├── docker-compose.yml
│   ├── k8s/
│   └── helm/
├── docs/                    # This spec folder
└── turbo.json

Tenant in scope for MVP

  • Tenant: Ashoka University
  • Slug: ashoka
  • Domain rule: @ashoka.edu.in emails containing _ug25 or _ug2024 → auto-create as student
  • Custom columns: c1 = CPP attended, c2 = IPP attended
  • Feature flags: all on for MVP