Architecture

Technical architecture of the Objectuve platform — system design, data models, API surface, and authentication.

Sections

• System Design — monorepo structure, backend/frontend architecture, infrastructure, and Mermaid diagrams
• Data Models — core domain models, relationships, and ERD
• API Reference — GraphQL endpoint, queries, mutations, and subscriptions
• GraphQL API Reference — complete type reference with field documentation, mutations, and queries
• API Versioning — versioning strategy, GraphQL evolution approach, when to introduce URL versioning
• Authentication — Clerk JWT flow, session tokens, demo login, and user sync
• GraphQL Integration — required queries, mutations, and subscription patterns for frontend development
• Admin Dashboard — component architecture, GraphQL operation catalog, auth flow, polling strategy
• Agent Runner — execution lifecycle, MCP tool pipeline, brand-voice filter, webhook contract, OIDC auth
• PWA Augment — service worker registration, Workbox caching, ConnectionStatusBar offline status, update flow, and OBJ-32 integration
• Offline Contract — what works offline, what's queued (checkInHabit/addGoalEvent), the Apollo cache persistence boundary, staleness, and failure handling (v4.58)
• Connected Apps Integration Framework — Activity Nexus data model, adapter pattern, connectedApps GraphQL query, and the token-encryption gate (v4.14 Phase 1)
• Community Room Authorization — CommunityAccessPolicy's team-room membership rule, the archived-room server-side write guard, and how both differ from team-lifecycle management permissions (v4.35 Phase 1)
• Toolchain Version Matrix — current → target versions for Ruby/Rails/Node/Vue toolchains across all 7 packages, and the per-major cost-benefit verdicts (vue-router 4→5, Vite 7→8, TypeScript 5→6) gating ionic_frontend's convergence

Architecture Proposals

Forward-looking architecture proposals (pending human review or approved for implementation):

• Periodic Load Testing Strategy — k6 OSS load testing, phased rollout (staging-only), monthly regression tracking
• DDD Documentation Refresh — May 2026 — update bounded contexts, context map, domain events after v1.6–v1.11 milestone deliveries
• Critical Path — User Coupling Decision — decided and shipped (OBJ-2370); kept as the architectural record for the Critical Path → Gamification migration

Architecture Audits

Point-in-time objectuve-keystone domain audits from the v4.3 Keystone Architecture Sweep (2026-07-09/10) — read-only source-vs-docs sweeps, each domain's own resolution status noted at the top of its file. Historical record, not living documentation; see the milestone narrative for the sweep's full context.

• AI Coaching
• AI Workforce
• Content Moderation, Admin, GDPR
• Gamification
• Goal Tracking
• Platform
• Social, Feedback
• Teams
• User Identity, Critical Path

Key decisions

• Single GraphQL endpoint — all data access through POST /graphql
• Interaction pattern — business logic in app/interactions/, keeping resolvers thin
• PublicRecord — all API-exposed models use public_id instead of database IDs
• Clerk auth — RS256 JWTs verified via JWKS, sent as SessionToken header

Last updated: 2026-09-17 (v4.58 Phase 6, OBJ-3745: added Offline Contract page link)