AssessIQ — Architecture & Module Documentation

Type: reference — This page gives the repository layout, local setup steps and the documentation index.

Scenario-driven, tier-based, hybrid-graded role-readiness assessment platform. The first real use is a university aptitude pilot; designed multi-tenant and embeddable from day one.

Local Development

Prerequisites

• Node.js 22 LTS — nvm install 22 && nvm use 22
• pnpm 9 — corepack enable && corepack prepare [email protected] --activate
• Docker — for local Postgres + Redis

Setup

# 1. Install dependencies
pnpm install

# 2. Start local Postgres + Redis
docker run -d --name aiq-pg \
  -e POSTGRES_USER=assessiq -e POSTGRES_PASSWORD=CHANGE_ME -e POSTGRES_DB=assessiq \
  -p 5432:5432 postgres:16-alpine
docker run -d --name aiq-redis -p 6379:6379 redis:7-alpine

# 3. Create your local env file
cp .env.example .env.local
# Generate required secrets:
echo "ASSESSIQ_MASTER_KEY=$(openssl rand -base64 32)" >> .env.local
echo "SESSION_SECRET=$(openssl rand -base64 32)" >> .env.local
# Then edit .env.local: set DATABASE_URL password, Google OAuth credentials, etc.

# 4. Apply migrations
DATABASE_URL=postgres://assessiq:CHANGE_ME@localhost:5432/assessiq \
  pnpm tsx tools/migrate.ts

# 5. Bootstrap first tenant + admin user for local dev (direct SQL).
#    No bootstrap script exists in tools/ or package.json. Run this once;
#    replace placeholders with your real values. In production, the platform
#    super admin creates companies from the Platform page
#    (docs/runbooks/customer-onboarding.md).
docker exec aiq-pg psql -U assessiq -d assessiq -c "
  INSERT INTO tenants (id, slug, name) VALUES
    ('00000000-0000-0000-0000-000000000001', 'my-org', 'My Organisation');
  INSERT INTO tenant_settings (tenant_id) VALUES
    ('00000000-0000-0000-0000-000000000001');
  INSERT INTO users (tenant_id, email, name, role) VALUES
    ('00000000-0000-0000-0000-000000000001',
     '[email protected]', 'Admin', 'admin');
"

Start the app (two terminals)

# Terminal 1 — API
pnpm --filter @assessiq/api dev

# Terminal 2 — Web (http://localhost:5173)
pnpm --filter @assessiq/web dev

Run tests

pnpm test          # unit + integration (testcontainers — no local DB needed)
# E2E: see apps/web/e2e/README.md

---

How to use this repo with Claude Code

1. Always start with docs/PROJECT_BRAIN.md — it gives Claude (and you) the orientation needed to navigate everything else.
2. For cross-cutting questions (auth, deployment, data model, etc.), point Claude at the matching docs/ file.
3. For implementing a feature, point Claude at the relevant modules/<n>-<name>/SKILL.md plus the docs files it lists as related. Each module's SKILL.md tells Claude what is in scope, what is out, what its dependencies are, and what help text it owns.
4. When schema changes, update both the migration AND docs/02-data-model.md in the same change.
5. When API surface changes, update docs/03-api-contract.md in the same change.

Map

docs/PROJECT_BRAIN.md             ← READ FIRST in every session
README.md                    ← this file

docs/
├── 01-architecture-overview.md  ← explanation: system context, parts, data flows
├── 02-data-model.md           ← Postgres schema + RLS
├── 03-api-contract.md          ← REST endpoint catalog
├── 04-auth-flows.md            ← Google SSO + TOTP + embed JWT + API keys
├── 05-ai-pipeline.md           ← Claude Code on VPS (Phase 1) + multi-stage grading
├── 06-deployment.md            ← VPS, Docker Compose, Caddy, Cloudflare
├── 07-help-system.md           ← Tooltip + drawer architecture
├── 08-ui-system.md             ← Tokens, components, theming
├── 09-integration-guide.md     ← how-to: host-app embed + REST + webhook integration
├── 10-branding-guideline.md    ← Visual identity: typography, palette, layouts, idioms
├── 11-observability.md         ← Logs, streams, metrics
├── 12-test-coverage.md         ← reference: test coverage map
├── 13-email-system.md          ← SMTP, templates, queue
├── 14-credentialing.md         ← reference: certificates, signing, verify, PDF
└── STYLE.md                    ← Documentation standard: page types, sentences, Vale

modules/
├── 00-core/SKILL.md          ← Foundation utilities
├── 01-auth/                  ← Identity, sessions, MFA, JWT, API keys
├── 02-tenancy/                ← Multi-tenant isolation
├── 03-users/                  ← User records, roles, invitations
├── 04-question-bank/          ← Packs, levels, questions
├── 05-assessment-lifecycle/   ← Cycles, invitations, state machine
├── 06-attempt-engine/         ← Taking the assessment
├── 07-ai-grading/             ← AI grading pipeline (Claude Code CLI on the VPS)
├── 08-rubric-engine/          ← Anchors, bands, scoring DSL
├── 09-scoring/                ← Aggregation, archetype, leaderboard
├── 10-admin-dashboard/        ← Admin UI
├── 11-candidate-ui/           ← Candidate UI
├── 12-embed-sdk/              ← Iframe embed + JS snippet
├── 13-notifications/          ← Email, webhooks, in-app
├── 14-audit-log/              ← Append-only audit trail
├── 15-analytics/              ← Reports, exports
├── 16-help-system/            ← Tooltip framework + help content
├── 17-ui-system/              ← Design tokens + components
├── 18-certification/          ← Signed certificates, public verify
├── 19-billing/                ← Usage metering, plans, entitlements
└── 20-data-rights/            ← DPDP/GDPR access, erasure, retention

infra/                          ← (populated as you build) docker-compose, nginx, scripts

Phase 0 — what to build first

Recommended order to get a thin slice working end-to-end:

1. 00-core — env, logger, errors, request context. Foundation.
2. 17-ui-system — token CSS + a handful of primitives (Button, Input, Card, Stack). You will need these for every screen.
3. 02-tenancy + 03-users — minimal CRUD; one tenant + one admin user seeded.
4. 01-auth — Google SSO + TOTP. This is the gate; everything else lives behind it.
5. 16-help-system — get the framework wired (HelpTip, HelpProvider, public read API). Even with stub content. Then content fills in as you build screens.
6. Smoke test: admin can log in via Google + TOTP, see an empty dashboard with help tooltips. Phase 0 done.

Then Phase 1 (author + take), then Phase 2 (grade + report), as laid out in docs/PROJECT_BRAIN.md.

What is next from the user

• Provide the UI template. Drop it under modules/17-ui-system/templates/<vendor-name>/ and follow the integration plan in docs/08-ui-system.md.
• Provision the DNS for assessiq.in in Cloudflare (proxied A record to VPS IP; zone-level Authenticated Origin Pulls ON). Canonical host as of 2026-05-22 — see docs/06-deployment.md § "Domain switch to assessiq.in".
• Create a Google Cloud OAuth client and capture client_id + client_secret for .env.
• Install and log in to the Claude Code CLI on the VPS. Production AI grading uses it (AI_PIPELINE_MODE=claude-code-vps), so no ANTHROPIC_API_KEY is needed. See docs/05-ai-pipeline.md.