Capablio

Handbook

Survey platform vision

Status: now implemented. The forge360 FastAPI package ships every PLN-* capability described on this page. Authoritative flags: feature-status.md. Engineering docs: forge360/README.md (API, crypto, lifecycle). The…

Updated

Status: now implemented. The forge360 FastAPI package ships every PLN-* capability described on this page. Authoritative flags: feature-status.md. Engineering docs: forge360/README.md (API, crypto, lifecycle). The offline pipeline and Studio remain for local PDF analysis; forge360 runs the survey loop itself.

Why

Today the system starts from Thomas International PDFs produced elsewhere. The planned platform closes the loop: it runs the 360 survey itself (based on the same questions/sections the current parser understands), produces the same two artifacts (feedback PDF + snapshot PDF), and adds richer, privately-encrypted commentary — while keeping personal data readable only by the subject and their direct HR.

Roles and permissions (PLN-ID-01…05)

Authentication: sign-in with Google. Authorization derives from two directories:

  • Org hierarchy — who manages whom (managers, team structure).
  • HR hierarchy — which HR person owns which organization; HR people also roll up into their own hierarchy.
Role Personal data (scores, comments, rich answers) Aggregate analytics Survey completion status PDF downloads PDP content
Subject (the person surveyed) Full — own data only Own report Own survey No (receives PDFs from HR by email) Full — own plan only
Direct HR (owns the subject's org) Full — for their designated org's people Yes, their orgs Yes, their orgs Yes — one-time, per completed survey No
Upper HR (above the direct HR) No — aggregates only, same as managers Yes, their designated orgs Yes, their designated orgs No No
Manager No — GDPR/EU-compatible views only Yes, their teams Yes, their teams No No
System operator / DBA No — cannot decrypt anything personal General system stats only — No No

Data-classification rule of thumb: anything traceable to an identified individual (scores, verbatim comments, rich answers, PDP) is personal; counts, averages over groups, and completion percentages are aggregate.

REST API (PLN-API-01)

The platform is API-first: every capability is a REST endpoint guarded by bearer tokens (issued after Google sign-in, scoped to the caller's role and orgs). The web UI is a client of the same API. This mirrors how the current local Studio already separates UI from the HTTP layer (app-api.md) — but adds authentication, which the local Studio deliberately does not have.

Survey lifecycle (PLN-SRV-01…04)

  1. Initiate — HR starts a period survey for one of their org structures. A period is linked to a quarter (e.g. 2026-Q3); one active survey per person per period.
  2. Invite — the system generates per-person email text outlining the process: who will be asked, what raters will see, the timeline, and confidentiality rules. HR sends these emails themselves; the system does not send mail.
  3. Collect — raters respond through the conversational UI (below). HR and the subject's manager see completion status per team; never the answers.
  4. Wrap up — when a person's survey is complete, the system renders a feedback PDF and a snapshot PDF (same shape the current parser consumes) and offers them to the direct HR only as a download. The files are generated on demand and not stored (PLN-ENC-04).
  5. Hand over — after HR confirms the survey outcome was communicated, the system generates a results-access email for the subject; HR attaches the PDFs themselves. The subject then gets platform access to work with their results.
  6. Develop — the subject builds a PDP from their results (same interview logic as today's Studio — pdp.md), stores it encrypted, and marks goals complete over the period (PLN-PDP-02/03).

Conversational survey UI (PLN-UI-01/02)

The respondent experience is a guided conversation, not a form:

  • One question/section at a time, matching the sections of the current 360 questionnaire (12 competencies, 54 statements, importance ranking, open questions) so the wrap-up PDFs stay compatible with the existing pipeline.
  • Visible progress (answered / remaining) at all times.
  • The UI facilitates: it can rephrase a question, prompt for concrete examples, and invite optional richer commentary beyond the fixed scales — that richer layer is the platform's added value over the PDF-only flow and is stored only in the encrypted envelope described below.

Encryption model (PLN-ENC-01…04)

Design goal: someone with physical access to the database and the system cannot extract personal data (PLN-ENC-03). Sketch:

  • Every user has a key pair; private keys are held client-side (unlocked at sign-in), never stored server-side in plaintext.
  • Personal survey payloads are envelope-encrypted to exactly two recipients: the subject and their direct HR (PLN-ENC-01). Upper HR, managers, and operators have no decryption path.
  • The PDP is encrypted to the subject only (PLN-ENC-02); the server stores ciphertext plus non-personal progress counters (for PLN-PDP-04 stats).
  • Aggregates shown to managers/upper HR are computed at write time from consented scale values into separate, non-reversible aggregate records — analytics never require decrypting personal payloads.
  • Wrap-up PDFs are rendered in memory for the one-time HR download and are not persisted (PLN-ENC-04).

Design questions

Topic Status Notes
Re-encryption when direct HR changes Resolved Client reseal flow (/api/envelopes/pending-reseal, /api/envelopes/reseal)
Aggregate extraction Resolved Write-time consented_scores → AggregateRecord; no decrypt for managers
Key recovery when user leaves Open See key-recovery.md
Trusted enclave for aggregates Deferred Client pre-encryption chosen for v1

Non-goals

  • The system never stores generated PDFs.
  • The system never sends email — it generates text; HR sends.
  • No plaintext personal data at rest, including backups and logs.
  • No decryption capability for operators, upper HR, or managers — by construction, not by policy.

Relationship to the implemented system

Surface Role
Capablio (forge360 on Cloud Run) End-user SaaS — tenants, surveys, encryption, /app UI, HR dashboards, subject results/PDP
Studio (feedback360/app_server.py) Operator back-office — KB corpus (/kb-admin), orchestrator (/orchestrator), pipeline visibility
capablio-worker (local + Cloudflare Tunnel) Privileged execution — KB LCDL/CDP, PDP AI, pipeline, Cursor agent jobs
Existing piece Reuse in the platform
parse_360.py data contract (12/54 structure) Question catalog + wrap-up PDF shape
analyze.py deterministic metrics Server-side analytics on decrypt-free aggregates and subject-side full analytics
render_html.py report + wiki Subject-facing results view in Capablio /app (/api/surveys/{id}/results/render, wiki routes)
PDP engine (pdp.md) Subject-side PDP interview; optional FORGE360_PDP_AI_REMOTE=1 routes AI to worker
Verify harness Wrap-up PDF ↔ collected-data reconciliation; verify_report_json gates export and full HTML
Remote job broker RemoteJob + operator/worker APIs; KB enrich and heavy jobs dispatch to local gateway