01 · Selection principles

Four rules that decided every choice below

Boring where it's load-bearing. Money, identity, and the event log run on technology with a decade of operational history. Novelty is spent on the matching and pricing layers, where mistakes are recoverable.
One schema, many stores. Every service reads the same entity vocabulary. Adding a store is allowed; forking the vocabulary is not.
Swappable at the seams. Each of the six seams from the unified stack gets a versioned contract. The technology behind a seam can change without the product noticing — that is the entire mechanism by which A becomes B becomes C.
A small team ships it. Every choice is weighed against a five-to-eight person team in the first year. A stack that needs fifteen specialists is not a plan.

02 · The stack at a glance

Layer by layer, what runs it

The eight layers mapped to concrete technology. Everything in the launch column exists, is documented, and has a hiring pool.

Layer	Launch technology	Migration target
01 Semantics	PostgreSQL schema with JSONB attribute bags; entity shapes modelled on the spatial-web vocabulary; JSON Schema definitions versioned in the repo as the single source of truth.	HSML entities on a shared graph; the JSON Schema definitions become the mapping layer.
02 Identity	W3C Decentralized Identifiers (`did:web` for institutions, `did:key` for members) + W3C Verifiable Credentials; keys in device secure storage; consent scopes enforced by Postgres row-level security.	Spatial-web identifiers linked to the same DIDs; credentials become portable across domains.
03 Trust	Python scoring service over the event log; deterministic, versioned, replayable. No ML in the trust path at launch.	Trust as a native graph dimension; scores become verifiable claims rather than a service's output.
04 Matching	Python service: LLM API for conversation and extraction, embeddings in `pgvector`, hybrid retrieval, explicit scoring policy. Tool-calling interface to all other services.	Active-inference matcher behind the identical interface; later per-member agents.
05 The current	PostgreSQL double-entry ledger, integer minor units, serializable transactions; scheduled flows as first-class rows; demurrage as a nightly job.	Flows expressed as protocol contracts; balances held agent-centrically.
06 Consensus	Hash-chained append-only event log in Postgres, with periodic public anchoring of a Merkle root. Custodial, tamper-evident, exit-ready.	Holochain (Rust/WASM) for agent-centric domain validation.
07 Settlement	Single database transaction — atomicity is free inside one ledger.	Interledger or HTLC-style swaps for cross-domain value.
08 Pricing	Python service implementing the published index as pure, versioned functions with full audit output.	Same interface; the function body becomes coherence-derived when simulation supports it.

03 · Languages

Three, and no more than three

Language count is a hiring and maintenance cost. Three is justified because each covers a domain the others handle badly.

TypeScriptProduct, API, web, mobile

Node with Fastify for the API layer, React for web, React Native via Expo for mobile. One language and one set of shared type definitions from the database row to the phone screen, which for a small team is worth more than any per-component optimisation. Types generated from the JSON Schema entity definitions, so a schema change breaks the build rather than production.

ConsideredElixir/Phoenix is arguably a better fit for a real-time, coordination-heavy social system, and its fault tolerance suits neighbourhood-scale reliability. It loses on hiring pool, especially in Brazil, and on shared types with the client. Revisit only if concurrency becomes the constraint, which at neighbourhood scale it will not.

PythonIntelligence, trust, pricing

FastAPI services for the matcher, the trust scorer, and the pricing index. The ecosystem for embeddings, retrieval, evaluation, and eventually active-inference libraries lives here and nowhere else. These three services are the ones expected to change most often; keeping them separate from the product API means they can be rewritten without touching the money path.

DisciplinePricing and trust must be pure and replayable: same inputs, same outputs, version stamped on every result. If a member disputes a price or a score, the answer must be reproducible months later.

RustLater — the distributed substrate

Not needed at launch. It enters when domain validation moves to Holochain, whose application logic compiles to WASM and is written in Rust. Naming it now matters for one reason: the validation rules that will eventually be written in Rust are being decided today, in the form of the coherence norms encoded in the event log. Write those rules as explicit, testable predicates from the start and the migration is a port rather than a redesign.

Non-negotiable across all three: money is never a floating-point number. Unity is stored as integer minor units with an explicit scale, all balance changes are double-entry, and no service outside the ledger may write a balance — only append an entry.

04 · Data layer

One database does almost all of it

The strongest cost-saving decision available: PostgreSQL with extensions replaces four separate systems at this scale, and each can be split out later when a specific query pattern actually hurts.

Need	Choice	Why not a dedicated system
System of record	PostgreSQL	Serializable transactions are what makes both-or-neither settlement free rather than a distributed-systems problem.
Semantic search	`pgvector`	A dedicated vector database earns its keep in the millions of embeddings. A neighbourhood has thousands. Same transaction, same backup, no sync problem.
Geography	PostGIS	Bioregion as a real spatial query rather than a text tag — and it is the natural source for geo-anchored graph objects at migration.
Flexible entity attributes	JSONB columns	Lets entities carry graph-shaped attributes without a graph database, which is precisely the hedge the HSML-shaped requirement calls for.
Consent enforcement	Row-level security	Consent scopes enforced by the database rather than by every application code path. The one place where a missed check is unrecoverable.
Queues, cache, sessions	Redis	The one genuinely necessary second store. Job scheduling for demurrage, flow runs, and notification fan-out.
Media & documents	S3-compatible object storage	Asset photos, condition records, credential attachments. Never in the database.
Analytics	Read replica, later a warehouse	Circulation reporting must never contend with settlement.

The event log is the spine

A single append-only table carries every settlement, confirmation, governance vote, trust-affecting act, and agreement state change. Each row stores the hash of its predecessor, making the log tamper-evident without a chain. Every other structure in the database — balances, trust scores, agreement status — is a materialised projection that can be rebuilt from the log alone. This is what makes the whole migration story credible: the log is the thing that moves to a distributed substrate, and everything else is derived.

Local-first, because neighbourhoods have bad signal

The client keeps a local replica of the member's own data and syncs when it can, using a CRDT library so concurrent edits merge rather than conflict. This is a usability requirement in the field, and it is also the honest first step toward members holding their own data — the same capability, arriving early and for practical reasons.

05 · API contracts

The interfaces that make it one product

Internal and client-facing

REST over HTTP, specified in OpenAPI, generated from the same JSON Schema entity definitions. Versioned per seam, with deprecation windows. Chosen over GraphQL because the seams need explicit versioned contracts more than the client needs flexible queries, and because municipal and institutional integrators can consume OpenAPI without learning anything new.
Server-sent events for the conversational stream and live confirmations. Simpler than websockets for a mostly-read UI.
An internal event bus — Redis streams at launch — carrying the same events the log records, so the trust scorer, notifications, and analytics react without polling.
Webhooks outbound for institutions: a congregation's calendar system, a business's accounting export, a municipal parks system.

The NI's tool interface — the piece that unifies the product

The Natural Intelligence does not have privileged database access. It is an orchestrator that calls the same internal APIs a screen would, through a declared tool interface: search_offers, check_availability, propose_exchange, price_exchange, request_confirmation, read_trust_standing. Three consequences, and they are the reason the architecture holds together:

Every action the NI takes is an action a member could have taken, and is logged identically. There is no shadow path.
Permissions are enforced once, at the API, not separately for humans and for the agent.
Swapping the model or the entire matching approach changes nothing else, because the tool contract is the seam.

External services consumed

Service	Purpose	Posture
LLM API	Conversation, extraction, summarisation, translation.	Behind an adapter with a documented prompt contract. Assume it will be replaced at least twice.
Speech-to-text	Voice-first onboarding and matching, in local languages.	Non-optional. Voice is the accessibility answer for the members this project most wants to reach.
Embeddings	Semantic retrieval over offers, needs, and assets.	Store the model version with every vector; a model change means a re-index, not a mystery.
Geocoding & maps	The Map surface, proximity, bioregion boundaries.	Prefer an open data source; boundaries are community-defined, not vendor-defined.
Push, email, SMS	Confirmations, flow reminders, assembly notices.	SMS matters more than push in the target neighbourhoods.
Calendar	Availability for time, access windows, agreements.	Open calendar standards, so institutions can connect what they already run.
Credential verification	Elevated vetting for care roles only.	Per-jurisdiction, consented, minimal disclosure. Never a general requirement.

06 · Distributed ledger

The honest answer: no blockchain at launch

This is the section most likely to disappoint and most important to get right. Every property the project needs from a chain at launch — tamper-evidence, auditability, atomicity, exit rights — is achievable without one, and a chain would add the risk it is meant to remove.

Launch · hash-chained log with public anchoringRuns today

The append-only event log chains each entry to the previous by hash. Periodically — daily is ample — the root of that chain is published to a public blockchain. Anyone can then verify that the history they were shown has not been rewritten, without the project operating a chain, paying per-transaction costs, or exposing member data. Cost is a few transactions a month; benefit is genuine third-party verifiability during the custodial phase.

What this does not giveIt does not remove the operator's ability to see data, and it does not distribute control. Those arrive with the substrate migration, and until then the custodial phase should be named plainly wherever the peer-to-peer narrative appears.

Migration · Holochain for domain validationEmerging, live

Holochain is the right shape for this system precisely because it is not a blockchain: there is no global consensus and no shared chain, which means no throughput ceiling and no reason for a neighbourhood's ordinary exchanges to be validated by strangers. Each member holds their own source chain; each domain's validation rules are its own code; agreement propagates by gossip among peers who have reason to care. That is the murmuration, implemented.

SequencingMigrate governance records first, then trust attestations, then settlement — riskiest last. Each stage is reversible because the Postgres log remains authoritative until the corresponding stage is proven.

Cross-domain · Interledger, as the first candidateWorth investigating now

Inter-domain settlement does not require every domain to share a chain. The Interledger Protocol was designed for exactly this problem — moving value across heterogeneous ledgers, including ordinary databases, using conditional transfers that either complete on both sides or unwind. It is mature, neutral, and would let a neighbourhood on Postgres settle with a bioregion on Holochain and a partner network on something else entirely, without any of them converging on one technology. This deserves a serious evaluation alongside whatever swap rails the partner ecosystem provides, because it removes a dependency rather than adding one.

Deliberately not: an on-chain transferable token

Issuing Unity as a transferable on-chain asset would contradict the non-convertibility posture that keeps the regulatory framing defensible, and would attract speculation into a currency whose entire design intent is circulation rather than accumulation. Anchoring for verifiability, yes. A tradeable token, no — and that refusal is a feature to state publicly, not a limitation to apologise for.

07 · Infrastructure

Managed, per-region, boring

Containers on a managed platform, deployed as a modular monolith plus the three Python services. Not microservices — module boundaries in one deployable, matching the seams, split out only when a specific module needs independent scaling. A five-person team running twelve services is a team that ships nothing.
Managed PostgreSQL with point-in-time recovery. The one thing never self-hosted.
Per-region deployment, because domains are geographic and data residency law is not. A Brazilian neighbourhood's data stays in Brazil, a European one in Europe. This aligns the legal requirement with the federation architecture instead of fighting it.
Key management in a managed KMS for issuer keys; member keys never leave the device.
Infrastructure as code and CI/CD from the first week, because a community-run domain must eventually be deployable by someone who is not the original team.
OpenTelemetry for tracing, structured logs, error tracking. One trace should follow a single exchange from the member's sentence through match, price, confirmation, and settlement.
Everything open source under a licence consistent with a commons held in trust, decided before the first commit rather than after the first fork request.

08 · How it converses

One product, at runtime

The same exchange traced through the actual components. Note that the NI appears as one caller among several, and that the ledger is reached by exactly one path.

CLIENTS
  Expo mobile app · PWA          local replica, CRDT sync
        │  REST + SSE  ·  DID auth
        ▼
EDGE
  API gateway                    rate limit · authn · consent scope
        │
        ▼
CORE  (TypeScript, one deployable)
  ┌──────────────┬──────────────┬──────────────┬──────────────┐
  │ Registry     │ Agreements   │ Ledger       │ Governance   │
  │ offers·assets│ flows·terms  │ only writer  │ votes·circles│
  └──────┬───────┴──────┬───────┴──────┬───────┴──────┬───────┘
         └──────────────┴──────┬───────┴──────────────┘
                               ▼
                    PostgreSQL  pgvector · PostGIS · JSONB · RLS
                    append-only event log  hash-chained
                               │
                     ┌─────────┴─────────┐
                     ▼                   ▼
              Redis streams        daily Merkle root
                     │                   └──▶ public anchor
        ┌────────────┼────────────┐
        ▼            ▼            ▼
INTELLIGENCE  (Python, called via tools — no direct DB access)
  Matcher        Trust scorer      Pricing index
  LLM·embeddings  replay of log     pure versioned fns
        │
        └──▶ calls back into CORE through the same public API

─────────────────  MIGRATION SEAMS  ─────────────────
  event log      ──▶  Holochain, domain by domain
  entity schema  ──▶  HSML graph, same shapes
  cross-domain   ──▶  Interledger / swap rails
  matcher        ──▶  active-inference, same tool contract
  pricing fn     ──▶  coherence-derived, same signature

The unification, stated in one paragraph

A member speaks. The client sends it to the gateway, which resolves their identity and consent scope. Core hands the utterance to the matcher, which reads through the same public API any screen uses, retrieves candidates from pgvector and PostGIS, asks the pricing service for a number and its factors, and proposes an exchange. Both parties confirm. Core's ledger module — the only component permitted to write a balance — records the settlement and the confirmations as entries in the hash-chained log, in one serializable transaction, which is what makes both-or-neither settlement true rather than aspirational. Redis carries the resulting events to the trust scorer and the notification worker. Tonight, demurrage runs as a scheduled job and the log's root is anchored publicly. Every surface in the product — Conversation, Wallet, Registry, Circle, Map — is a different projection of that one log. There is no second system.

That last sentence is the whole integration answer. Eight layers, five surfaces, three languages, one database, one log. The layers are conceptual; the log is physical. When someone asks how a nature-inspired eight-layer architecture becomes a single coherent product, the answer is that every layer writes to and reads from the same append-only history, and everything else is a view.

09 · Build order

What gets written first

Entity schema and JSON Schema definitions. All five value classes, HSML-shaped. Nothing else starts until this is reviewed, because everything else inherits it.
Event log and ledger module. Double-entry, integer units, hash chaining, replayable projections. Test it with property-based tests before a single screen exists.
Identity and consent. DIDs, credentials, row-level security policies. The one layer where retrofitting is not possible.
Registry and agreements. Assets, availability, terms, recurring flows.
The API and its OpenAPI contract, then the NI tool interface on top of it — in that order, never the reverse.
Matcher, pricing, trust as three Python services against the finished contract. These are the first things that will be rewritten and should be the last things that are load-bearing.
Client surfaces, Conversation first, the other four as inspection views.

Team shape for year one: two backend engineers on core and ledger, one on identity and infrastructure, one Python engineer across matcher, pricing, and trust, one client engineer, one designer, and — not optional — legal counsel running in parallel from week one on currency classification and asset-access liability, since that workstream and not any engineering task sets the launch date.