Handbook
Product Architecture and Main Functionality
Architecture target (AFF v0.1). Implementation flags live in implementation-status.md. Do not treat this document as a shipped product contract.
Updated
Architecture target (AFF v0.1). Implementation flags live in implementation-status.md. Do not treat this document as a shipped product contract.
Product positioning
Capablio should be positioned as an adaptive longitudinal feedback operating system. The differentiator is not merely a survey builder or a 360 report. It is the orchestration layer that decides which small set of questions to ask, to whom, when, why, and when not to ask again.
Primary personas
| Persona | Primary needs |
|---|---|
| Individual | Understand patterns, request feedback, manage PDP goals, see progress |
| Respondent | Complete a short, relevant survey with confidence and anonymity |
| Manager | Understand team signals, support development, close feedback loops |
| Tenant admin / People team | Configure packs, schedules, anonymity, roles, reporting, and integrations |
| Framework editor | Author, review, version, translate, and retire constructs and questions |
| Coach | Interpret 360 patterns and connect them to concrete development actions |
| Security / compliance admin | Control access, retention, data residency, export, audit, and deletion |
Capability map
Question and framework studio
- Construct taxonomy and competency framework editor
- Question-family and cadence-variant editor
- Answer-scale library
- Question quality checklist and linting
- Translation workflow
- Version comparison and migration
- Global, vendor, tenant, and imported source labels
- Approval and publishing workflow
- Deprecation and replacement mapping
Pack studio
- Create packs from questions and bundles
- Define anchors, rotation pools, mandatory groups, and optional groups
- Define respondent routing and role applicability
- Define quotas by dimension, relationship, and question type
- Simulate coverage and survey length before publishing
- Fork or overlay global packs without losing lineage
Scheduler and delivery
- Daily, weekly, bi-weekly, monthly, quarterly, annual, anniversary, and event-driven schedules
- Tenant timezone and fiscal calendar
- Quiet days, holidays, vacations, and blackout periods
- Email, Slack, Microsoft Teams, in-app, and link delivery
- Reminder and expiration policies
- Multiple active programs with a shared exposure ledger
Adaptive assembly
- Cooldown eligibility
- Anchor reservation
- PDP and event-trigger reservation
- Constrained weighted rotation
- Atomic and splittable bundles
- Coverage-cycle tracking
- Feasibility simulation
- Deterministic replay for audit and debugging
Feedback and 360
- Self, manager, peer, direct report/team, customer, partner, and custom relationships
- 90/180/270/360 configurations
- Internal and external raters
- Rater nomination and approval
- Minimum anonymity thresholds
- Relationship-specific questionnaires
- Qualitative prompts and evidence examples
PDP and coaching
- Goal creation from a report, import, manual selection, or coaching session
- Baseline, action, evidence, support, and outcome check-ins
- Cooldown overrides for linked questions
- Milestones, target dates, owners, and supporters
- Coaching notes with separate permissions
- Closure criteria and follow-up period
Analytics
- Individual trend, self-versus-others, and relationship views
- Construct and question-family drill-down
- Coverage, fatigue, response, and Not Observed dashboards
- Dispersion and confidence indicators
- PDP progress using multiple evidence types
- Team and organization aggregates with suppression rules
- Item-quality analytics for framework owners
Administration
- Organizational hierarchy and matrix relationships
- Role and attribute-based assignments
- CSV import and directory sync
- SSO, SCIM, API, and webhooks by entitlement
- Branding, localization, and communications
- Audit logs and data lifecycle controls
- Plan entitlements and usage metering
Main end-to-end workflows
Recurring pulse
- Admin assigns a pack to a population and cadence.
- Scheduler creates a survey window.
- Assembly engine filters candidates against applicability, cooldown, exposure, and policy.
- Mandatory, anchor, PDP, and rotating items fill the quota.
- Survey is delivered through the preferred channel.
- Responses are aggregated subject to anonymity thresholds.
- Coverage and exposure ledgers are updated.
- Manager and individual receive appropriate insights and actions.
Quarterly 360 pulse
- Subject or admin chooses raters by relationship.
- The platform validates anonymity and exposure sufficiency.
- Relationship-specific variants are selected from the same construct families.
- Results are shown by relationship only when the minimum group size is met.
- Development themes may be proposed, but the individual confirms what becomes a PDP objective.
Annual deep review
- A larger anchor set is used to preserve year-over-year comparability.
- Rotating modules cover strategic priorities and tenant-specific capabilities.
- Qualitative prompts ask for continue/start/stop/risk/evidence.
- Report includes trends from recurring pulses, but does not average incompatible scales or observation horizons.
External assessment import
- Admin or individual uploads a supported file or structured export.
- Adapter stores the original source and extracts competencies, items, scores, relationships, dates, and comments.
- Mapping is exact, semantic, manual, or unmapped.
- Imported evidence appears as a separate baseline layer.
- A user may select imported themes for a PDP; no automatic blending is performed.
Logical architecture
flowchart LR
UI[Web / Mobile / Slack / Teams] --> API[Application API]
API --> LIB[Framework and Pack Service]
API --> SCH[Schedule Service]
SCH --> ASM[Survey Assembly Engine]
ASM --> EXP[Exposure and Coverage Ledger]
ASM --> PDP[PDP Policy Engine]
API --> RESP[Response Service]
RESP --> PRIV[Anonymity and Privacy Service]
PRIV --> ANA[Analytics Service]
API --> IMP[Import Adapters]
API --> ENT[Entitlements and Tenant Policy]
API --> EVT[Event Bus and Webhooks]
Administrative surfaces
- Library — constructs, families, variants, scales, translations, status.
- Packs — composition, quotas, relationships, cadence defaults, coverage simulation.
- Programs — assignments, schedules, channels, populations, reminders, quiet periods.
- People — subjects, managers, teams, matrix relationships, external raters.
- PDP — templates, trigger policies, active goals, overrides, milestones.
- Analytics — program health, coverage, fatigue, response quality, trends.
- Imports — Thomas and generic CSV imports, mapping review, lineage.
- Governance — approvals, audit, anonymity, retention, deletion, export.
- Billing — subject seats, plan entitlements, usage limits, add-ons.