Skip to main content

Functional Specification Document: ChainAlign Internal Decision OS (Codename "Judgment Engine")

Formal Specification: Thought-to-Decision Pipeline & Multi-Source Capture Platform (v5.1)​

A decision intelligence platform that structures, analyzes, and learns from every internal choice — building an auditable graph of organizational reasoning. Designed for multi-tenant use: first, as an internal operating system for ChainAlign; later, as a customer-facing decision OS.

Feature NameChainAlign Internal Decision OS
Component LayerInternal Product
StatusFinal
Core GoalTo transform unstructured internal thoughts into structured, traceable decision artifacts, creating a "Judgment Graph" that documents how ChainAlign is built.
Primary MetricTracing Ratio: Percentage of finalized internal product/architectural decisions that have a direct lineage to a captured thought artifact in the system.

1. Overview & Strategic Imperative​

This internal OS operationalizes ChainAlign’s core hypothesis—that organizational judgment can be structured, measured, and improved.

This document specifies the design for an internal "Decision Operating System" for ChainAlign. The system's purpose is to "dogfood" our core value proposition: making decision-making a structured, data-driven, and traceable process. It will replace ad-hoc note-taking with a dedicated capture-and-analysis pipeline supporting multiple entry points: web UI, iOS app, file uploads, and future API integrations. Every significant internal decision will be made and documented through this system, creating an auditable and invaluable Judgment Graph of our company's reasoning.

Unlike conventional productivity tools, the Judgment Engine treats every note, deliberation, and outcome as data — forming the backbone of ChainAlign's own meta-intelligence. It is both our internal operating system and the first living demonstration of our platform's promise.

Multi-Source Architecture: Thoughts can originate from any external source—Claude conversations, Slack discussions, email, meeting notes, research articles, or direct user input. All converge into a unified decision intelligence system, enabling ChainAlign to build organizational memory across all communication channels.

Multi-Tenant by Design: From day one, the system is built to support multiple tenants. This allows seamless transition from internal (ChainAlign team) to customer-facing (multi-tenant SaaS) as the product matures.

The workflow is defined by a "Thought-to-Decision" pipeline:

  1. Capture: Unstructured thoughts from multiple sources are captured as Notes (web, iOS, files, integrations).
  2. Structure: AI agents analyze Notes to add semantic meaning (future phase).
  3. Promote: Enriched Notes are promoted into a Decision Problem.
  4. Evaluate: Multiple Scenarios are created to model potential solutions to the problem.
  5. Decide & Learn: A final Decision is recorded, its impact is tracked, and the lessons are distilled into a reusable ReasoningBank.

2. System Architecture​

2.1. High-Level Data Flow​

The Unified Data Plane shall support both synchronous (REST) and asynchronous (event-driven) ingestion to enable real-time and batched reasoning workflows. Multiple entry points converge into a single decision intelligence backend.

[Web UI (React)]          [iOS App (SwiftUI)]       [File Upload]      [API Integrations]
(text, paste, files)      (text, voice, paste)      (.md, .txt, etc)   (future: Slack, GitHub, etc)
      |                           |                        |                    |
      └───────────────────┬───────┴────────────────────────┴────────────────────┘
                          V
                [API Gateway + Auth]
                          |
                          V
        [ChainAlign Backend - Judgment Engine Service]
                 |                              |
          ┌──────┴──────┐                ┌─────┴──────┐
          V             V                V            V
    [Note Service] [Problem Service] [Decision Service] [Analysis Service]
          |             |                |             |
          └──────┬──────┴────────────────┴─────────────┘
                 V
        [Unified Data Plane]
             |              |
        [PostgreSQL]    [Graph Store] (future)
        - notes         - decision lineage
        - problems      - entity relationships
        - scenarios     - reasoning chains
        - decisions
        - reasoning_bank

2.2. Core Components​

Client Layer (Multiple Entry Points):

  • Web UI (React): Primary interface for creating notes, making decisions, and browsing decision history. Supports text input, paste from clipboard, and file uploads.
  • iOS Companion App: Native SwiftUI app for capturing notes on-the-go. Supports text, voice-to-text, and paste from clipboard. Uses Core Data for offline sync.
  • File Ingestion: Direct upload of markdown (.md), text (.txt), and other formats.
  • API Integrations (Future): Slack, GitHub, Zoom, email forwarding, and other external sources.

Backend Layer:

  • API Gateway: Secure entry point with JWT-based authentication. Routes requests based on source and operation type.
  • Judgment Engine Service: Monolithic backend service (for MVP) or microservices architecture (future). Manages:
    • Note ingestion and storage
    • Problem definition and context aggregation
    • Scenario modeling and decision recording
    • Outcome tracking and ReasoningBank distillation

Data Layer:

  • PostgreSQL: Single source of truth for all structured data:
    • notes: Raw thoughts from multiple sources
    • decision_problems: Structured problems derived from notes
    • scenarios: Alternative solutions to be evaluated
    • decisions: Final choices and their rationale
    • reasoning_bank_items: Validated lessons and patterns
    • source_metadata: Attribution and context for external sources
  • Graph Store (Future): Typed relationship graph. Edges include :ORIGINATED_FROM, :SOLVED_BY, :INFORMED_BY, etc. Enables advanced pattern recognition and retrospective analysis.

Event & Integration Layer (Future-ready):

  • The architecture SHALL support event-driven extensions via Pub/Sub or Kafka for:
    • Asynchronous AI analysis on note ingestion
    • Webhook notifications to external systems (GitHub issue creation, Slack updates)
    • Real-time decision intelligence broadcasts

3. Authentication & Authorization​

  • FR-AUTH-1 (Abstraction Layer): The system SHALL implement a central ChainAlignAuth service layer.
  • FR-AUTH-2 (Internal JWT): This layer SHALL issue a standardized internal ChainAlign JWT. All backend services MUST only trust this internal JWT.
  • FR-AUTH-3 (Standardized Claims): The internal JWT SHALL contain sub (user_id), tenant_id, and role.
  • FR-AUTH-4 (Token Exchange): A secure endpoint (POST /api/internal/v1/auth/exchange) SHALL exist to exchange an external token for an internal JWT.
  • FR-AUTH-5 (MVP Provider): The initial implementation SHALL use Firebase Auth.
  • FR-AUTH-6 (Audit Logging): Every authentication event SHALL be recorded in the system_audit_log table.

4. Functional Requirements​

Implementation Roadmap: Web-First with Two Testing Rounds​

The system is built in phases with clear deployment gates and testing rounds:

┌─ Phase 1: MVP Web Backend + Web UI ─┐
│ [Deploy to Production]               │
└────────────────────────────────────┬─┘
                    ↓
    ┌─ Testing Round 1: Internal Web Usage ─┐
    │ [Pramod uses it for real decisions]   │
    │ [Gather feedback on UX & workflows]   │
    └────────────────────────────────────┬──┘
                    ↓
    ┌─ Phase 2: iOS App + Bidirectional Sync ─┐
    │ [Optional: Parallel desktop web clipper] │
    └────────────────────────────────────┬────┘
                    ↓
    ┌─ Testing Round 2: Multi-Platform ─┐
    │ [Capture on iOS, decide on web]   │
    │ [Cross-platform data integrity]   │
    └────────────────────────────────────┘
                    ↓
    ┌─ Future Phases: AI, Graph Store, API Integrations ─┐

Phase 1: MVP - Web Backend + Multi-Source Capture (Web & File Upload)​

Goal: Deploy a working decision intelligence system within 2 weeks that Pramod can use immediately for actual ChainAlign decisions.

4.1.1. Multi-Source Note Ingestion​

  • FR-CAPTURE-1 (Web Note Entry): The Web UI SHALL provide a text input form for capturing notes directly.
  • FR-CAPTURE-2 (Clipboard Paste): The Web UI SHALL support pasting content from clipboard (Claude conversations, emails, etc.).
  • FR-CAPTURE-3 (File Upload): The Web UI SHALL support uploading .md, .txt, and other text file formats.
  • FR-CAPTURE-4 (Source Attribution): Each note SHALL include optional source_origin (e.g., "Claude", "Slack", "Research", "Direct Input") and source_metadata (e.g., URL, file name).
  • FR-API-1 (Note Ingestion Endpoint): The backend SHALL expose POST /api/internal/v1/notes accepting: 
    {
      "content": "string",
      "source_type": "web_paste | file_upload | direct_input",
      "source_origin": "string (optional)",
      "source_metadata": "object (optional)"
    }
  • FR-GUARD-1 (Tenant Isolation): All operations SHALL be immutably scoped to the tenant_id.

4.1.2. Note Listing & Management​

  • FR-LIST-1 (Note Listing): The backend SHALL expose GET /api/internal/v1/notes with pagination and filtering.
  • FR-LIST-2 (Web UI Display): The Web UI SHALL display all notes with creation timestamp, source origin, and content preview.
  • FR-DELETE-1 (Note Deletion): The backend SHALL support DELETE /api/internal/v1/notes/:id (soft delete for audit trail).

4.1.3. Decision Problem Creation (Promote)​

  • FR-PROMOTE-1 (Manual Promotion): The Web UI SHALL provide a "Promote to Decision Problem" action on each note.
  • FR-PROMOTE-2 (Problem Creation): This action SHALL POST to /api/internal/v1/notes/:id/promote and create a DRAFT record in decision_problems table.
  • FR-PROMOTE-3 (Problem Enrichment): The promotion form SHALL allow the user to:
    • Set a problem title (auto-suggested from note content)
    • Add additional context (why this matters)
    • Link related notes (multi-select)
    • Set impact area (e.g., "architecture", "product", "operational")

4.1.4. Decision Problem Viewing & Scenario Creation​

  • FR-PROBLEM-LIST (Problem Listing): The backend SHALL expose GET /api/internal/v1/decision-problems with status filtering.
  • FR-PROBLEM-VIEW (Problem Detail): The backend SHALL expose GET /api/internal/v1/decision-problems/:id with full context (related notes, scenarios, decisions).
  • FR-SCENARIO-1 (Scenario Creation): The backend SHALL expose POST /api/internal/v1/decision-problems/:id/scenarios accepting: 
    {
      "name": "string",
      "description": "string",
      "predicted_impact": "object (free-form JSON)"
    }
  • FR-SCENARIO-UI (Web Scenario Builder): The Web UI SHALL provide a form to create 2-3 scenarios, each with name and description.

4.1.5. Decision Recording​

  • FR-DECISION-1 (Decision Endpoint): The backend SHALL expose POST /api/internal/v1/decisions accepting: 
    {
      "decision_problem_id": "uuid",
      "chosen_scenario_id": "uuid",
      "final_rationale": "string (why this scenario was chosen)"
    }
  • FR-DECISION-IMMUTABLE (Immutability): Once created, a decision record SHALL be immutable (no updates, only reads).
  • FR-DECISION-UI (Web Decision UI): The Web UI SHALL provide a form to select the chosen scenario and record rationale.

4.1.6. Authentication & Multi-Tenant Scoping​

  • FR-AUTH-1 through FR-AUTH-6: (Reuse from current FSD Section 3) All existing auth requirements apply.

Phase 1A: Testing Round 1 - Internal Web Usage​

Goal: Validate that the system supports your actual decision-making workflow.

Activities:

  • Use ChainAlign to capture decisions about M36.2+ feature development
  • Capture decisions from Claude conversations and other sources
  • Test scenarios for architectural choices (e.g., "React → Vue?" decision)
  • Provide feedback on UX, schema gaps, and workflow friction
  • Gather real decision data for retrospectives

Success Criteria:

  • ✅ Zero data loss during note capture and sync
  • ✅ Can promote at least 5 notes to decision problems
  • ✅ Can create and record decisions with multiple scenarios
  • ✅ Web UI is responsive and intuitive

Phase 2: iOS App + Bidirectional Sync​

Goal: Enable capturing thoughts on mobile and syncing bidirectionally with the web backend.

4.2.1. iOS App Core​

  • FR-IOS-1 (SwiftUI Project): Set up Xcode project with SwiftUI and Core Data.
  • FR-IOS-2 (Core Data Model): Create Core Data entities for offline note storage (mirrors PostgreSQL schema).
  • FR-IOS-3 (Text Input): Implement text input form for capturing notes.
  • FR-IOS-4 (Paste Support): iOS app SHALL allow pasting content from clipboard.
  • FR-IOS-5 (Offline Queue): Capture notes offline using Core Data; sync when connection available.

4.2.2. iOS ↔ Backend Sync​

  • FR-SYNC-1 (Push Sync): iOS app SHALL sync local notes to backend via POST /api/internal/v1/notes/batch.
  • FR-SYNC-2 (Pull Sync): iOS app SHALL periodically fetch new decisions/problems from backend for offline viewing.
  • FR-SYNC-3 (Conflict Resolution): If a note is edited both locally and remotely, last-write-wins.
  • FR-SYNC-4 (Firebase Auth): iOS app SHALL use Firebase SDK for auth and exchange tokens via /api/internal/v1/auth/exchange.

4.2.3. Cross-Platform Viewing​

  • FR-CROSS-1 (Web ← iOS Notes): Notes captured on iOS appear in web UI within minutes of sync.
  • FR-CROSS-2 (iOS ← Web Decisions): Decisions made in web UI appear in iOS app's read-only view.

Phase 2A: Testing Round 2 - Multi-Platform​

Goal: Validate cross-platform experience and data consistency.

Activities:

  • Capture notes on iOS during meetings or conversations
  • Sync to backend and view in web UI
  • Make decisions in web UI; verify they appear in iOS
  • Test offline capture on iOS; verify sync on reconnect
  • Provide feedback on mobile UX and sync reliability

Success Criteria:

  • ✅ Notes sync within 30 seconds of reconnection
  • ✅ Web and iOS show consistent decision state
  • ✅ No data corruption or loss during sync
  • ✅ iOS app is responsive even on slow networks

Phase 3: Semantic Structuring & AI Analysis (Future)​

  • FR-ANALYZE-1 (Asynchronous AI Analysis): On note ingestion, an async process MAY classify intent and extract entities (optional, lower priority).
  • FR-ANALYZE-2 (Store Analysis): Analysis output MAY be stored in notes_analysis table.
  • FR-ANALYZE-3 (Explainability Metadata): AI analysis MAY include reasoning trace.

Phase 4: Learning & Reflection (Future)​

  • FR-IMPACT-1 (Record Outcome): The system MAY provide POST /api/internal/v1/decisions/:id/outcome for outcome recording.
  • FR-REASONING-1 (Distill to ReasoningBank): The system MAY provide AI-powered distillation to ReasoningBank.
  • FR-REASONING-2 & FR-REASONING-3: (Future) ReasoningBank management and traceability.
  • FR-GRAPH-1 (Decision Lineage): (Future) Graph store for relationship visualization.

Together, these steps transform every decision from a one-time act into a reusable unit of organizational judgment.

5. Data Models & Schema (MVP)​

All tables SHALL include standard audit fields (created_at, updated_at, metadata) to enable temporal analytics and reasoning provenance.

5.1. notes Table​

Captures raw thoughts from multiple sources. Entry point to the decision intelligence pipeline.

CREATE TABLE notes (
    id                 UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id          UUID NOT NULL,
    content            TEXT NOT NULL,

    -- Source attribution (multi-source support)
    source_type        TEXT CHECK (source_type IN ('web_paste', 'file_upload', 'direct_input', 'api_integration')) DEFAULT 'direct_input',
    source_origin      TEXT, -- 'Claude', 'Slack', 'Email', 'GitHub', etc. (user-defined)
    source_metadata    JSONB DEFAULT '{}', -- {url, conversationId, fileName, integrationId, attributedTo}

    -- Created by user
    created_by         UUID NOT NULL,
    created_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    -- Future: AI classification & embeddings
    -- extracted_entities JSONB, -- {topics: [], people: [], technologies: []}
    -- vector_embedding vector(1536),

    tags               TEXT[] DEFAULT '{}',
    metadata           JSONB DEFAULT '{}'
);

5.2. decision_problems Table​

Captures the problem space and aggregates context.

CREATE TABLE decision_problems (
    id                 UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id          UUID NOT NULL,
    title              TEXT NOT NULL,
    context_text       TEXT,
    source_notes       UUID[] DEFAULT '{}',
    impact_area        TEXT,
    status             TEXT CHECK (status IN ('draft','gathering_options','ready_for_decision','archived')) DEFAULT 'draft',
    created_by         UUID NOT NULL,
    created_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at         TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    tags               TEXT[] DEFAULT '{}',
    metadata           JSONB DEFAULT '{}'
);

5.3. scenarios Table​

Represents a potential option or solution for a decision problem.

CREATE TABLE scenarios (
    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id           UUID NOT NULL,
    decision_problem_id UUID NOT NULL REFERENCES decision_problems(id),
    name                TEXT NOT NULL,
    description         TEXT,

    -- Predicted outcomes (free-form JSON; structured retrospectively)
    predicted_impact    JSONB DEFAULT '{}', -- {effort: "3 days", risk: "medium", learningValue: "high"}
    confidence          NUMERIC(5,2) DEFAULT 50,

    created_by          UUID NOT NULL,
    created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    metadata            JSONB DEFAULT '{}'
);

5.4. decisions Table​

An immutable record of the final choice.

CREATE TABLE decisions (
    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id           UUID NOT NULL,
    decision_problem_id UUID NOT NULL REFERENCES decision_problems(id),
    chosen_scenario_id  UUID NOT NULL REFERENCES scenarios(id),
    decision_maker_id   UUID NOT NULL REFERENCES users(id),
    final_rationale     TEXT NOT NULL,

    decided_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    -- Outcome tracking (future)
    actual_outcome      JSONB DEFAULT '{}', -- {timeframe: "1w", metrics: {...}, success: true/false}

    metadata            JSONB DEFAULT '{}'
);

6. API Surface Definition (MVP Phase 1)​

Authentication (Existing):

EndpointMethodDescription
/api/internal/v1/auth/exchangePOSTExchanges an external auth token for an internal ChainAlign JWT.

Notes (Multi-Source Capture):

EndpointMethodDescription
POST /api/internal/v1/notesPOSTCreate a new note (text, paste, file upload, etc.)
GET /api/internal/v1/notesGETList all notes with pagination & filtering
GET /api/internal/v1/notes/:idGETFetch a single note with full metadata
DELETE /api/internal/v1/notes/:idDELETESoft-delete a note (for audit trail)

Decision Problems:

EndpointMethodDescription
POST /api/internal/v1/notes/:id/promotePOSTPromote a note to a decision_problem draft
GET /api/internal/v1/decision-problemsGETList all decision problems
GET /api/internal/v1/decision-problems/:idGETFetch a problem with related notes & scenarios

Scenarios:

EndpointMethodDescription
POST /api/internal/v1/decision-problems/:id/scenariosPOSTCreate a scenario for a problem
GET /api/internal/v1/decision-problems/:id/scenariosGETList scenarios for a problem

Decisions:

EndpointMethodDescription
POST /api/internal/v1/decisionsPOSTRecord a final decision (immutable)
GET /api/internal/v1/decisionsGETList all decisions
GET /api/internal/v1/decisions/:idGETFetch a single decision

Future Endpoints (Phase 2+):

EndpointMethodDescription
POST /api/internal/v1/notes/batchPOSTBatch sync notes from iOS app
POST /api/internal/v1/decisions/:id/outcomePOSTRecord actual outcome (retrospective)
POST /api/internal/v1/decisions/:id/distillPOSTDistill into ReasoningBank
GET /api/internal/v1/reasoning-bankGETList ReasoningBank entries

7. Future Phases (Out of Scope for MVP Phase 1)​

Phase 3: Semantic Analysis & Enrichment​

  • AI-Powered Intent Classification: Auto-classify notes by decision type (architecture, product, process, operational)
  • Entity Extraction: Extract key entities (people, technologies, dates, metrics) from notes
  • Vector Embeddings: Generate embeddings for semantic search across decision history
  • Explainability: Show reasoning traces for AI classifications

Phase 4: Learning & Reflection Loop​

  • Outcome Recording: Multi-horizon outcome tracking (1 week, 1 month, 1 quarter)
  • Retrospective Analysis: Compare predicted impact vs. actual impact
  • ReasoningBank: AI-powered distillation of lessons into reusable decision patterns
  • Traceable Reuse: Track which future decisions referenced past lessons

Phase 5: Graph Store & Advanced Analytics​

  • Decision Lineage Graph: Visualization of how thoughts → problems → decisions → outcomes
  • Pattern Recognition: Identify recurring decision patterns and their success rates
  • Cognitive Analytics: Measure tracing ratio, decision latency, reasoning reuse rate as internal OKRs

Phase 6: Enterprise & Integration​

  • API Integrations: Slack, GitHub, Zoom, email, calendar event context
  • Web Clipper: Capture web articles and research as decision context
  • Enterprise Federation: SAML/OIDC support for corporate SSO
  • Collaborative Decisions: Multi-user input on scenarios and outcomes
  • Customer-Facing SaaS: Full multi-tenant support with team collaboration

Phase 7: Operational Excellence​

  • Workflow Automation: Trigger tasks in GitHub/Linear/other tools from decisions
  • Mobile Push: iOS notifications for decision milestones
  • Custom Integrations: SDK for embedding Judgment Engine into other tools
  • Advanced Search: Full-text search, faceted filtering, saved searches

ChainAlign doesn’t just record what we decide — it learns how we think.