> ## Documentation Index
> Fetch the complete documentation index at: https://docs.presschain.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How PressChain separates protocol authority, publication records, evidence, application interfaces and projections.

# Architecture

PressChain is designed as a protocol with several cooperating surfaces, not as a single application and not as a monolithic smart contract. That distinction is central to building on it correctly.

At the bottom is the V3 chain and its contracts. Above that are canonical models and rulebooks that define what records mean. Read models, indexers and APIs project that state into forms that applications can query efficiently. PressKey provides the browser signing and identity surface for user-authorized actions. The Portal and Explorer are clients of the protocol, not the source of protocol truth.

```mermaid theme={null}
flowchart TB
  U[User or newsroom] --> PK[PressKey]
  PK --> RPC[V3 RPC]
  APP[Custom application] --> RPC
  RPC --> C[Capsule and protocol contracts]
  C --> EV[Events and state]
  EV --> IDX[Independent indexer and projections]
  IDX --> API[Read APIs]
  IDX --> EX[Explorer]
  API --> APP
  C --> M[Canonical models and rulebooks]
```

## Protocol authority

The protocol repository owns semantic authority for PressChain. That includes V3 configuration, Solidity contracts, economic enforcement policy, role and bond definitions, canonical record semantics and the implementation material needed to deploy and index the network.

This is deliberately different from letting each application decide that role 3 means one thing, or that a Capsule status means something else. When a rule changes through an approved protocol process, clients are expected to adopt the canonical definition rather than silently creating incompatible behavior.

## Capsule architecture

Publication state is decomposed into focused registries. Current source includes dedicated Capsule content, contributor, evidence, metadata locator and revision contracts. V3 contributor and evidence registries build on a shared Capsule core interface whose canonical key is a `bytes32` Capsule ID.

This separation produces useful boundaries. Contributor accounting can enforce share constraints without bloating the evidence contract. Evidence can maintain its own status and vote tally. Revision history can evolve without mutating the original content commitment. A client can query only the domain it needs.

A typical application flow is:

1. Create or identify the Capsule publication record.
2. Persist canonical off-chain metadata at a stable URI.
3. Commit content and metadata hashes to protocol state.
4. Render contributors and attribution from the contributor registry.
5. Attach evidence through the correct evidence path.
6. Observe revisions, verification activity and later protocol events.

## Data availability versus authority

PressChain does not require every byte of journalism to live in contract storage. URLs and metadata locations can point to web, content-addressed or archival storage, while hashes provide a deterministic commitment to the referenced material.

This creates a useful distinction:

* **Availability** answers whether a client can retrieve an artifact.
* **Integrity** answers whether the retrieved artifact matches the committed hash.
* **Authority** answers which identity or protocol actor was authorized to make the state transition.
* **Interpretation** answers what the protocol says that record means.

An application should preserve all four. A pretty card with a URL but no hash verification is incomplete. A valid hash from an unauthorized actor is also incomplete.

## Read paths and write paths

PressChain intentionally separates read convenience from write authority. Direct JSON-RPC and contract calls remain the lowest common denominator. Indexers and read APIs make application queries easier, but they do not replace chain state.

The current Rust API binary is read-only and exposes a bounded surface around bounty state. It should not be treated as a generic transaction relay. User-authorized writes should be signed by the user through PressKey and submitted to the network without a server taking custody of the private key.

## Independent indexing

Indexing is a projection layer. It should be restartable from authoritative events and state, idempotent under replay and resilient to reorganization. It may enrich records for search and presentation, but an enriched field must never masquerade as canonical chain data.

This matters for products that combine PressChain with external analytics. External intelligence can be extremely useful, but it remains a separate source with its own provenance. PressChain does not become the owner of another trust system simply because an application displays both.

## Why these boundaries matter

The architecture is optimized for long-lived records and multiple independent clients. A Capsule created by one newsroom should still be understandable to an Explorer, a browser extension, an archive and a future application that did not exist when the Capsule was published.

That only works when the contract, model and authority boundaries are explicit. PressChain therefore favors stable identifiers, canonical schemas, deterministic hashes, explicit permissions and auditable state transitions over application-specific shortcuts.