Shared Core Architecture

Draft 0.1 — 2 August 2026
This document defines a target architecture and decision framework. It does not require one cloud provider, database, programming language, blockchain, identity vendor, or AI model provider.

Objective

The ANUKA shared core exists to let independent products reuse trustworthy network capabilities without becoming one giant application or one centrally operated company.

The core must make it easier to build a resident product while preserving:

product autonomy;
tenant and legal-entity boundaries;
portable identity and evidence;
granular authorization;
replaceable infrastructure;
verifiable operations;
safe AI-agent access;
independent failure domains;
voluntary exit.

The architectural rule is:

Centralize contracts and shared guarantees; decentralize product decisions, data ownership, and replaceable implementations.

Architectural layers

Layer 1 — Public specifications

Repository-native documents, schemas, vocabularies, compatibility rules, and governance records.

This layer includes:

Foundation documents;
JSON Schemas;
OpenAPI and AsyncAPI documents;
event type registry;
capability registry;
credential and attestation schemas;
decision records;
conformance profiles;
security and privacy requirements.

Specifications are authoritative only for their declared version and status.

Layer 2 — Shared identity and authorization

Reusable services for:

account and organization identifiers;
authentication;
identity assurance state;
roles and delegated capability grants;
OAuth-style consent and data requests;
service and agent principals;
policy decisions;
revocation and expiry.

Authentication proves control of an authenticator. Authorization determines whether a principal may perform a defined action on a defined resource in a defined context. The two must not be conflated.

Layer 3 — Canonical network records

Append-only or strongly versioned records for:

projects and resident products;
participation and affiliation;
opportunities and assignments;
contributions and reviews;
releases and experiments;
evidence packages;
credentials and attestations;
payments and ledger references;
governance proposals and decisions;
disputes, corrections, and revocations.

A canonical record does not imply that every payload is public or stored in one database.

Layer 4 — Shared execution services

Optional services that resident products may reuse:

notification delivery;
search and indexing;
webhook dispatch;
workflow orchestration;
payments integration;
file and evidence storage;
attestation issuance;
analytics aggregation;
agent tool gateway;
policy evaluation;
audit and observability pipelines.

Resident products may replace a shared service when the protocol contract is preserved.

Layer 5 — Product adapters

Product-specific integrations including:

browser extension surfaces;
Site SDK and GTM adapter;
web and mobile applications;
CMS and commerce plugins;
product APIs;
data connectors;
MCP servers;
command-line tools;
automation and agent workflows.

Adapters must not receive more authority than their product purpose requires.

Layer 6 — Resident products

Independent products retain control over:

roadmap;
pricing;
customer relationships;
private data;
staffing and contractors;
product-specific policies;
deployment cadence;
legal terms;
product-level incidents;
exit from ANUKA.

Using the shared core does not automatically create common ownership, joint employment, agency, partnership, franchise, or fiduciary relationships.

Core domains

The initial shared core is divided into bounded domains.

Domain	Primary responsibility
Identity	Principals, accounts, organizations, assurance, authenticators
Authorization	Roles, capability grants, policies, consent, revocation
Registry	Products, organizations, endpoints, protocol versions, status
Contribution	Opportunities, assignments, submissions, reviews, outcomes
Evidence	Claims, sources, evidence packages, credentials, attestations
Reputation	Contextual graph, capability evidence, disputes, corrections
Economy	Rewards, allocations, payment references, ledger entries
Governance	Proposals, decisions, roles, councils, constitutional records
Presence	Site manifests, extension discovery, modules, capabilities
Agent runtime	Tools, tasks, approvals, delegated actions, execution logs
Notifications	Preference-aware delivery and action requests
Audit	Security, authorization, financial, governance, and agent events

A domain may begin as a module in a modular monolith. Domain boundaries are logical before they are network boundaries.

Modular monolith first

ANUKA should not begin with dozens of microservices.

The recommended starting point is:

one versioned application deployment or a small number of services;
explicit domain modules;
separate schemas and ownership boundaries;
asynchronous events where independence is useful;
extraction only after operational evidence supports it.

A module may become a service when one or more conditions are true:

independent scaling is necessary;
security isolation is materially improved;
availability requirements differ;
a separate team owns the lifecycle;
an external protocol boundary already exists;
deployment coupling creates measurable harm.

Microservices are an implementation choice, not a maturity badge.

Tenant and legal-entity boundaries

Every request and record must resolve relevant ownership context.

Possible scopes include:

network-wide public specification;
Foundation-operated shared service;
resident organization;
resident product;
project environment;
participant-controlled record;
verifier-specific presentation;
legal-entity-specific financial record.

A generic tenant_id is not sufficient when legal responsibilities differ. Records may require explicit fields such as:

controller_organization_id;
operator_organization_id;
product_id;
legal_entity_id;
data_owner_id;
issuer_id;
subject_id;
policy_scope_id.

Cross-tenant access must be authorized through an explicit relationship, consent grant, public-data rule, or legal obligation.

Trust zones

Public zone

Unauthenticated documentation, public profiles, public specifications, public claims, and intentionally public evidence.

Public does not mean unvalidated, unrestricted reuse, or free of privacy and copyright constraints.

Participant zone

Authenticated participant data, private work records, consent grants, applications, saved items, and personal settings.

Organization zone

Company-controlled private records, integrations, team permissions, data rooms, product configuration, and financial information.

Restricted operations zone

Secrets, payment-provider credentials, signing keys, high-risk administrative tools, security evidence, and incident response systems.

Agent execution zone

Isolated execution context for tools, tasks, temporary credentials, approved data, and output validation.

Agent execution must not inherit unrestricted application or database authority.

Data storage principles

ANUKA may use multiple stores, but every data class must have one declared authoritative record.

Recommended patterns:

relational storage for transactional and strongly related records;
object storage for immutable evidence packages and artifacts;
search indexes as rebuildable projections;
graph projections for reputation and relationship traversal;
append-only audit storage for sensitive actions;
cache layers as disposable performance aids;
blockchain or public attestation networks only for selected integrity and portability use cases.

A search index, analytics warehouse, vector store, or model memory must never silently become the source of truth.

Canonical records and projections

The core distinguishes:

command — a request to change state;
decision — authorization and validation result;
canonical record — committed authoritative state or event;
projection — derived view optimized for a use case;
presentation — audience-specific disclosure;
attestation — signed claim about a record or result.

Derived projections must be rebuildable from declared sources or carry their own provenance and version.

API and event boundaries

Synchronous APIs are preferred when a caller requires an immediate authoritative answer.

Events are preferred when:

multiple consumers may react independently;
eventual consistency is acceptable;
the publisher should not know all consumers;
auditability benefits from immutable facts;
workflows cross product boundaries.

Commands and events must not share ambiguous names.

Prefer:

command: AcceptContribution
event: ContributionAccepted

Do not publish an event until the authoritative transaction has committed. Use an outbox or equivalent reliable publication pattern.

External contracts

ANUKA uses:

OpenAPI for request/response HTTP APIs;
JSON Schema 2020-12 for canonical JSON payload validation;
AsyncAPI for event-driven interfaces;
CloudEvents for the common event envelope;
OAuth and OpenID protocols for authorization and compatible identity flows;
MCP for model-facing tools, resources, apps, and tasks where appropriate;
OpenTelemetry for traces, metrics, and logs.

An external standard is adopted only for the use cases it actually covers. ANUKA-specific semantics remain explicitly versioned.

Capability-first design

Every mutating operation must map to a named capability.

Examples:

contribution.submit;
contribution.review;
product.release.approve;
evidence.presentation.request;
payment.refund.create;
governance.proposal.publish;
agent.tool.invoke;
organization.integration.manage.

Capabilities should be:

narrow;
composable;
resource-scoped;
time-bounded where practical;
auditable;
revocable;
safe to explain to a person.

A role is a maintained bundle of capabilities, not an authorization shortcut hidden in application code.

Policy enforcement

Authorization must be enforced server-side at every trusted boundary.

A policy decision should evaluate:

principal;
capability;
resource;
organization and product scope;
consent or delegation grant;
purpose;
environment;
assurance level;
risk state;
time and expiry;
incident restrictions;
legal or contractual hold.

User-interface visibility is not authorization.

Idempotency and retries

All externally retried mutations should support idempotency.

An idempotency record should bind:

caller or principal;
operation;
resource scope;
request hash;
idempotency key;
first result;
expiry.

A repeated key with materially different input must fail rather than execute a second action.

Events require stable identifiers so consumers can deduplicate deliveries.

Failure isolation

A failure in one resident product must not automatically disable the network.

Isolation requirements include:

product-scoped credentials;
rate limits and quotas;
separate queues or partition keys where practical;
circuit breakers for external dependencies;
bounded retries;
dead-letter handling;
product-level kill switches;
ability to disable one integration or capability;
financial and data segregation.

Shared services must publish failure modes and degraded behavior.

Consistency classes

Each operation should declare its consistency requirement.

Strong consistency

Used for:

authorization grants and revocation;
financial ledger entries;
assignment ownership;
product release approvals;
governance decision status;
credential status where immediate enforcement is required.

Read-your-writes consistency

Used for interactive workflows where a participant expects a submitted update to appear immediately.

Eventual consistency

Used for:

search;
analytics;
recommendation indexes;
reputation projections;
public activity summaries;
notification delivery.

Interfaces must not present eventually consistent projections as authoritative current state.

Environments

At minimum:

local development;
shared development;
staging;
production.

Sensitive production credentials and data must not be copied into lower environments by default.

Schemas and protocol versions should be tested across environments before production adoption.

Deployment principles

immutable build artifacts;
environment-specific configuration outside the artifact;
infrastructure as code;
automated rollback or safe forward recovery;
signed or provenance-attested releases where practical;
database migration discipline;
no manual production changes without durable records;
progressive delivery for high-risk changes;
explicit ownership and on-call expectations.

Buy, reuse, build

ANUKA should buy or reuse when a mature provider or open standard already solves the problem and replacement remains possible.

Likely reuse areas:

authentication;
payment processing;
transactional email;
object storage;
observability collection;
secrets management;
search infrastructure;
queues and workflow engines;
software composition analysis.

Build when ANUKA-specific network semantics create differentiated value:

contribution and quality graph;
consented Passport presentations;
product stewardship grants;
sponsored-feature lifecycle;
network presence and discovery;
evidence and attestation orchestration;
cross-product reputation portability.

Reference implementation versus protocol

A reference implementation demonstrates one path through the specifications.

It must not become the only conforming implementation by accident.

The project should separate:

normative schemas and requirements;
conformance tests;
example implementations;
hosted ANUKA services;
optional provider integrations.

Architecture decision records

Material choices require an ADR containing:

context;
decision;
status;
alternatives;
consequences;
security and privacy implications;
migration and reversal path;
affected protocol versions;
evidence and review date.

Examples include database selection, queue selection, identity provider, event envelope, MCP version, signing method, and service extraction.

MVP architecture

A practical initial system may contain:

Starlight specification site;
one application API with modular domains;
relational transactional database;
object storage for evidence;
background job and event queue;
Stripe Connect integration;
browser extension and Site SDK;
OAuth authorization and consent service;
MCP gateway for approved agent capabilities;
OpenTelemetry instrumentation and a centralized collector;
append-only audit records;
generated OpenAPI, JSON Schema, and SDK artifacts.

Architecture acceptance criteria

The first implementation is acceptable only when:

every public and agent operation maps to a documented capability;
tenant and legal-entity boundaries are explicit;
canonical records and projections are distinguishable;
events use stable IDs and versioned schemas;
financial and authorization mutations are idempotent;
sensitive actions are audited;
product failures can be isolated;
resident products can export protocol-level records;
shared services can be replaced without rewriting the entire network;
no AI agent has implicit database or administrative authority;
production changes are reproducible and reviewable.

Sources

Verification record

Sources opened and checked: 2 August 2026
Architecture status: Draft baseline
Provider selection: Not ratified
Conformance suite required before v1.0: Yes