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

# Architecture

> Understand the neobank API, transactional worker, provider boundary, and customer application.

# Understand the neobank architecture

The platform separates synchronous customer reads from asynchronous provider mutations. FastAPI authenticates and validates requests; PostgreSQL stores local policy and operation state; the worker performs provider writes from a transactional outbox; React tracks approval and completion.

```text theme={null}
Browser or agent
      |
      v
FastAPI + Auth0/CSRF/OAuth
      |
      +--> PostgreSQL operation + idempotency + outbox
      |                    |
      |                    v
      |              worker / scheduler
      |                    |
      v                    v
Vault ciphertext      LivePerfloAdapter
                           |
              app | Perfolio | fiat | cards | agent
```

## Process provider writes

The API persists an operation before any provider write. The worker commits `submitting` before money or authority submission. A definitive refusal becomes `failed`; a possible acceptance becomes `indeterminate` and is never retried.

Transfers and mandate creation first prepare a recipient grant, then enter `requires_action`. The browser opens only the exact trusted Perflo application origin. Approval polling verifies one unique active grant before payment or mandate activation.

## Reconcile with reads

Submitted transfers reconcile through transaction identifiers or hashes. Uncertain card actions reconcile through exact card reads. Uncertain revocations reconcile through the exact upstream grant. Missing or ambiguous evidence leaves the operation indeterminate for operator review.

## Project a neobank contract

The account API includes only fiat deposit accounts with safe masks. Unified activity filters and deduplicates customer-wide cash and payment feeds. Beneficiary destinations, approval sessions, and provider preparation data remain encrypted. Cards expose lifecycle state, last four digits, aggregate United States dollar balance, transactions, and hosted reveal.

## Enforce customer and agent authority

Customer routes require customer sessions. Operator routes can view and suspend but cannot move money. Agent execution requires an OAuth scope and an active customer mandate bound to the same client identifier. Upstream grant constraints and local atomic reservations must both pass.