# obqo — Complete Documentation

> obqo is a coaching, career services, and student success platform for higher education institutions. EU-hosted, GDPR-compliant, multi-tenant.

## Product overview

obqo replaces fragmented stacks (Symplicity, 12twenty, Microsoft PowerApps coaching tools, Excel reporting) with a single integrated platform. It is built for career-services departments, coaching teams, and programme directors at universities and business schools.

Key differentiators:
- Multi-tenant from day one: each faculty/school gets its own subdomain, data, and branding.
- AI-assisted note-taking: record coaching sessions, auto-transcribe (Whisper), generate structured summaries (Claude) — coach always reviews before saving.
- Career Signals: detect alumni career milestones via self-reporting and coach observations (no LinkedIn scraping). Draft personalised outreach with one-click send.
- EU-hosted: all data in Frankfurt (Supabase EU), no data leaves Europe.
- Built for institutional procurement: GDPR-compliant, audit trails, role-based access, signed BPA available.

## Features

### Coaching & sessions
- Log coaching sessions across 8 types: intake, follow-up, career-review, crisis, checkup, job-search, mock-interview, alumni-request.
- Coaching trajectories: group sessions into long-running student-coach relationships with goals.
- Session Notes (AI-assisted): record → transcribe (Whisper) → summarise (Claude Haiku) → coach reviews → save to dossier.
- Audio is automatically deleted after transcription (privacy by design).
- Full audit trail: consent, recording, transcription, AI draft, coach edits, save — every step logged.
- Session reminders: coach evening-before email + student morning-of email with Teams link and previous-session action items.

### Student management
- Roster with search, filter, bulk actions.
- CSV import for bulk student upload (column mapping, validation, duplicate detection).
- Student profile: pre-program background (role, company, industry, country), expected graduation, contact preferences, recording opt-out.
- At-risk detection: students with no session in 14+ days OR in-progress flow with no response in 5+ days.
- State-based student dashboard: content adapts to journey stage (new → onboarding → post-session → active → idle → completing).

### Flow engine
- Visual flow builder (React Flow): drag-and-drop questionnaire/form creation.
- 8 step types: question (text/long/select/scale/multiselect), info, file upload, branch logic.
- Token-based student access: HMAC-signed URLs, no student auth required to fill.
- Flow triggers: auto-assign flows on events (graduation, session completion, no-show, etc.).
- Flow template library: clone and customise pre-built flows per institution.

### Career tracking
- Job-application pipeline: Interested → Applied → Interview → Offer → Accepted (Kanban view).
- Pre/post programme career comparison with industry, country, timing.
- Placement matrix: timing breakdown (Before / During / Within 3 months / After) with world map.
- Time-to-employment analytics with per-bucket KPIs.

### Career Signals
- Coach quick-action: "Log career update" on alumni profile → AI drafts congratulations email → one-click send.
- Alumni self-report flow: automated annual email asking alumni to update their career status.
- Dashboard widget + dedicated /signals page with expandable cards (status: new / reviewed / actioned / ignored).
- Branded institutional emails via Truncus (SES).

### Events
- Event management with attendance tracking (registered / attended / no-show).
- Post-event ratings (1–5 stars + comments) with analytics integration.
- Invited → attended conversion funnel (from event targetProgrammes).
- Track × Event attendance matrix.

### Alumni Map
- Dashboard widget: compact world map with country dots and top-locations grid.
- Dedicated /alumni/map page: interactive map (react-simple-maps), hover tooltips, click → alumni panel.
- Career Signal pulse animation on countries with recent job changes.
- Filters: programme, year, industry.

### Analytics (7 tabs)
- Coaching: sessions, types, online/in-person, coverage, no-show, YoY with % of cohort toggle.
- Coaching Matrix: students × session-type pivot table with drill-through.
- Alumni Requests: dedicated tab for alumni coaching metrics.
- Events: attendance, ratings, track matrix, invited→attended funnel.
- Career: placement rate, time-to-employment, pre→post career change table.
- Engagement & Placement: engagement vs placement correlation.
- Placement Matrix: per-programme timing matrix with world map.
- All tabs: programme filter, FT/PT toggle, date range, CSV export.
- PDF report export: configurable sections, presets (executive summary / full / coaching only / career only).

### Reports Center
- Central /admin/reports page: select datasets, apply filters, download CSV (UTF-8 BOM, RFC 4180, formula-injection guard).
- Per-page CSV export on every data page.
- PDF report builder: same UI as analytics with print-optimised layout (SVG charts, page breaks, Geist Mono KPIs).

### Daily Coach Digest
- Personalised email Mon–Fri 07:00 CET.
- Five sections: today's sessions, students needing attention, career signals, flow updates, weekly statistics.
- Configurable: coaches choose which sections to include via /settings/me.
- One-click unsubscribe via HMAC-signed token (timingSafeEqual verified).
- Idempotent: same email gets at most one digest per day even on re-runs.

### Session reminders
- Coach: evening-before email (18:00 CET) with all of tomorrow's sessions grouped together.
- Student: morning-of email (08:00 CET) with session details, Teams link, action items from previous session.
- Cancelled sessions excluded by status filter (no false reminders).

### Email templates
- Per-org customisable templates: invitation, session reminder, flow assignment, event invitation.
- Org branding: institution logo + primary colour on all emails.
- Merge tags: {{studentName}}, {{coachName}}, {{orgName}}, {{date}}, {{flowTitle}}, {{eventName}}.
- Sent via Truncus (EU email infrastructure with SES under the hood).

### Microsoft 365 integration (optional)
- Outlook calendar sync: auto-create calendar event + Teams meeting link on booking.
- Auto-delete calendar event on cancellation.
- Best-effort: booking always works even when calendar credentials are missing.
- CalendarProvider abstraction supports Microsoft Bookings (Niveau 2, planned).

### Student portal (/my/*)
- Shared sidebar (same @vanmoose/dashboard-core as the coach portal).
- State-based dashboard: content adapts to student's journey stage (see "Student management").
- Self-service booking: pick coach + available slot, sticky bottom confirmation panel, Teams link in success state.
- Career tracker: add/update job applications with status pipeline.
- Flow player: complete assigned flows in-browser.
- Alumni networking: browse alumni, request introductions.
- Profile editor: pre-program background, expected graduation, recording opt-out, contact preferences.
- Session recording indicator + deletion request.

### Billing
- Stripe integration: checkout, webhooks, Customer Portal.
- Invoice management for BILLING_ADMIN role.
- Plan limits enforcement (students, coaches, storage, SSO).
- Past-due handling: 14-day grace period before read-only mode.

### Contextual help
- "?" button on every dashboard page opens a slide-out help panel.
- Per-page help content: description, key actions, tips.
- ~33 routes covered.

### Student documents
- Link-based (SharePoint / OneDrive / Google Drive URLs, not file upload — no storage costs, permissions stay in source-of-truth).
- Session Notes auto-linked as documents on save.
- Types: CV, motivation letter, certificate, report, notes, other.

## Architecture

- Framework: Next.js 15 (App Router), React 19.
- Database: PostgreSQL via Supabase EU (Frankfurt), Prisma ORM.
- Auth: Clerk (Google + Microsoft OAuth + magic link). NextAuth Prisma adapter for legacy compatibility.
- Email: Truncus (EU transactional email).
- AI: OpenAI Whisper (transcription), Anthropic Claude Haiku (summaries, career-signal emails).
- Calendar: Microsoft Graph API (optional).
- Billing: Stripe.
- Hosting: Vercel (fra1 region).
- Monorepo: pnpm workspace, vanmoose-nexus.

## Multi-tenant

- Each institution gets: {slug}.obqo.co subdomain, isolated data (Postgres RLS on every one of 35 obqo_* tables), custom branding (logo, primary colour), dedicated coaches and students.
- Tenant resolution: subdomain → Organization lookup in Next.js middleware (5-minute in-memory cache).
- New tenant setup: 5 minutes (create org, assign slug, invite admin via Clerk).

## Roles

| Role | Students | Build flows | Billing | Settings | Users |
|---|---|---|---|---|---|
| Coach | Assigned only | No | No | No | No |
| Flow Builder | Assigned only | Yes | No | No | No |
| Admin | All | Yes | No | Yes | Yes |
| Billing Admin | None | No | Yes | No | No |
| Owner | All | Yes | Yes | Yes | Yes |
| Super Admin | Cross-org | Yes | Yes | Yes | Yes |

## Pricing

- Core — €6,000/year. 150 students, 5 coaches, basic flows, career tracking, events, CSV export.
- Professional — €10,000/year. 500 students, 15 coaches, visual flow builder, SSO, AI features, alumni access, marketplace.
- Institution — €15,000–25,000/year. Unlimited students/coaches, REST API, SLA, custom domain, onboarding.
- Launch partners — free during pilot phase (UvA Amsterdam Business School is the founding partner).

## API

- Authentication: Bearer token in `Authorization` header.
- Base URL: `https://{slug}.obqo.co/api` or `https://obqo.co/api`.
- OpenAPI spec: `https://obqo.co/api/openapi.json`.
- Rate limit: 100 requests/minute per API key.

Key endpoints:
- `GET  /api/students` — list students (programme, status, search, limit).
- `POST /api/students` — create student.
- `GET  /api/coaching/sessions` — list coaching sessions (coachId, studentId, from, to).
- `POST /api/coaching/sessions` — book a coaching session.
- `GET  /api/career-signals` — list career signals (status, source).
- `POST /api/career-signals` — create career signal.
- `GET  /api/alumni/map` — alumni map data (countries + counts).
- `GET  /api/admin/analytics/{tab}` — analytics data per tab (coaching, events, career, engagement, placement-matrix, alumni-requests, coaching-matrix).

## Integration

- OpenAPI 3.0: `/api/openapi.json`.
- Agent manifest: `/.well-known/agent.json`.
- LLM docs: `/llms.txt` (summary), `/llms-full.txt` (this file).
- Agent guide: `/for-agents`.
- Email via Truncus: branded institutional emails.
- Calendar via Microsoft Graph: Outlook + Teams.
- MCP server: 6 obqo tools registered in `@vanmoose/mcp-server` (npm).

## Data residency

- All data stored in EU (Frankfurt, Germany — Supabase EU region).
- No data leaves Europe at rest.
- AI processing: OpenAI (transcription) and Anthropic (summaries) — neither uses customer data for model training under their enterprise / API terms.
- Audio recordings are automatically deleted after transcription completes.
- Audit log retained per institutional policy.

## Compliance

- GDPR-compliant; DPA on file with each tenant.
- ISO 27001 alignment (Supabase EU + Vercel SOC 2 Type 2 underlying infra).
- User-deletion cascade via Clerk webhook (right-to-erasure).
- Recording opt-out at student level, plus org-level disable.

## Links

- Website: https://obqo.co
- Dutch surface: https://obqo.nl
- API docs: https://obqo.co/api/docs
- OpenAPI: https://obqo.co/api/openapi.json
- Agent manifest: https://obqo.co/.well-known/agent.json
- LLM summary: https://obqo.co/llms.txt
- Agent guide: https://obqo.co/for-agents
- Comparison — Symplicity: https://obqo.co/vs/symplicity
- Comparison — Handshake: https://obqo.co/vs/handshake
- Comparison — 12twenty: https://obqo.co/vs/12twenty
- Contact: https://obqo.co/contact
- Security: https://obqo.co/security
- Privacy: https://obqo.co/privacy
- Terms: https://obqo.co/terms
- Accessibility: https://obqo.co/accessibility