Touli Core Architecture (HLD)

Purpose

This document defines the high-level architecture for:

• AI-assisted deed verification
• Deterministic points attribution
• Blockchain proof anchoring

It is designed for a hybrid stack that keeps the existing monorepo direction (Express/Nx + Postgres), while introducing worker-driven asynchronous pipelines.

Scope

• In scope: component boundaries, trust boundaries, data flow, and non-negotiable invariants.
• Out of scope: implementation details, migration execution, and infrastructure provisioning scripts.

Non-Negotiable Invariants

1. Rules first, AI second, humans third.
2. Points engine is deterministic and never calls AI.
3. Blockchain stores pseudonymous proofs only, never PII.
4. Wallet balance is a projection, while ledger entries are the source of truth.
5. Every economically relevant decision is reproducible from config snapshot + ledger history.

High-Level Component Map

flowchart LR
  mobileApp[MobileApp] --> apiGateway[ApiGateway]
  mobileApp --> adminConsole[AdminConsole]

  apiGateway --> submissionService[SubmissionService]
  apiGateway --> readApi[ReadApi]

  submissionService --> primaryDb[(PostgresPrimary)]
  submissionService --> eventBus[EventBusQueue]

  eventBus --> verificationWorker[VerificationWorker]
  verificationWorker --> rulesEngine[RulesEngine]
  verificationWorker --> visionAdapter[VisionAdapter]
  verificationWorker --> reviewService[ManualReviewService]
  verificationWorker --> primaryDb

  eventBus --> pointsWorker[PointsWorker]
  pointsWorker --> pointsEngine[PointsEnginePure]
  pointsWorker --> primaryDb

  eventBus --> anchorWorker[AnchorWorker]
  anchorWorker --> merkleBuilder[MerkleBuilder]
  anchorWorker --> chainAdapter[PolygonAlchemyAdapter]
  anchorWorker --> primaryDb

  primaryDb --> readApi
  primaryDb --> observability[ObservabilityPipeline]
  reviewService --> adminConsole

Trust Boundaries

flowchart TB
  subgraph userZone [UserZone]
    mobile[MobileClient]
  end

  subgraph appZone [ApplicationZone]
    api[ExpressApi]
    worker[BackgroundWorkers]
  end

  subgraph dataZone [DataZone]
    db[(Postgres)]
    storage[(ObjectStorage)]
  end

  subgraph externalZone [ExternalProcessors]
    ai[GeminiApi]
    chain[PolygonViaAlchemy]
    push[PushAndEmailProviders]
  end

  mobile --> api
  api --> worker
  api --> db
  worker --> db
  worker --> storage
  worker --> ai
  worker --> chain
  api --> push

Boundary rules:

• UserZone -> ApplicationZone: authenticated API requests only.
• ApplicationZone -> DataZone: least-privilege service accounts, audited writes.
• ApplicationZone -> ExternalProcessors: processor contracts + explicit purpose limitation.
• DataZone -> ExternalProcessors: no direct data-plane flow; all calls pass through controlled worker adapters.

System-Level Data Flow

sequenceDiagram
  participant U as UserApp
  participant A as ApiGateway
  participant Q as EventBus
  participant V as VerificationWorker
  participant P as PointsWorker
  participant D as Postgres
  participant B as AnchorWorker
  participant C as ChainAdapter

  U->>A: submitDeed(evidence,metadata)
  A->>D: createSubmission(status=pending)
  A->>Q: publishDeedSubmitted
  A-->>U: acceptedAndVerifying

  Q->>V: deedSubmittedEvent
  V->>D: storeVerificationResult
  V->>Q: publishVerificationCompleted

  Q->>P: verificationCompletedEvent
  P->>D: appendLedgerAndUpdateWalletProjection
  P->>Q: publishPointsCredited

  Q->>B: pointsCreditedEvent
  B->>D: stageAnchorLeaf
  B->>C: submitDailyMerkleRoot
  C-->>B: txHashAndReceipt
  B->>D: persistAnchorBatchStatus

Synchronous vs Asynchronous Responsibilities

• Synchronous (API request path):
  • Authenticate request
  • Validate schema and basic constraints
  • Persist initial deed submission
  • Return accepted response with tracking id
• Asynchronous (worker path):
  • Full verification, scoring, and review routing
  • Points calculation and ledger append
  • Blockchain leaf staging and root anchoring
  • Retention and cleanup jobs

Logical Ownership

• Submission service owns deed ingestion and basic validation.
• Verification worker owns confidence routing and outcome generation.
• Points worker owns deterministic scoring and ledger integrity.
• Anchor worker owns proof generation, batching, and chain reconciliation.
• Read API owns user-visible projections and status views.

Operational Success Criteria

• Deed submission API remains responsive under verification load.
• Verification pipeline can retry safely without double-credit outcomes.
• Ledger remains append-only and fully auditable.
• Chain outages do not block points crediting.