First-slice topology
The consumer purpose is earning money and creating, holding and trading asset bundles in customer subaccounts. The earning and bundle specification controls that product and its release acceptance. The rewards and income architecture adds merchant ingestion, campaign funding, a reward journal, independent payouts and provider income records. Home, Explore and Portfolio are the default destinations.
Browser
│
├── app.forage.finance ── Next.js web (no custody secrets)
│ │
│ ▼
└────────────────────── api.forage.finance ── Fastify on Railway
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
PostgreSQL Provider adapters Quote service
state + audit log read/execute lanes signed routes
│
User ── Abstract Global Wallet ── authorizes ── Canonical Accounts
│ │
│ bounded root session ├── provider lane
▼ ├── direct/basket lane
Automation Gateway ├── strategy/agent lane
│ └── cash lane
│ │
└────────────── Account Directory ────────────┤
▼
Account Instances
local smart accounts/provider books
│
▼
mirrors: policy + budget, not assets
The signer service and provider execution workers are future isolated services, not modules inside the public API. Their credentials should live in a managed HSM/MPC or equivalent signing boundary. PostgreSQL stores key references and policy state, never raw private keys.
This topology is an internal model, not the customer information architecture. The web presents one coherent Account flow and delegates provider selection, Account Instance provisioning, gas preparation, status normalization, and reconciliation to the API/orchestration layer. The end-user experience specification defines which details appear by default, at review, in Details, or only in Advanced views.
Deployable units
Web
Next.js App Router with React Server Components by default. Browser code handles presentation, user intent, and wallet-mediated signing. It does not hold provider API secrets or automation signer keys.
API
Fastify is the sole public business API. The initial server provides health, readiness, OpenAPI, CORS, security headers, rate limits, graceful shutdown, and shared runtime schemas. Every future mutation must add idempotency, audit, authorization, and a durable status.
Database
Railway PostgreSQL is the operational source of truth for offchain state. The initial package contains only audit-event and idempotency primitives; portfolio schemas should follow the accepted provider and custody model rather than precede it.
Contracts
The Foundry-ZKsync workspace targets Abstract for the root control plane. Forage assigns each logical lane a chain-agnostic Canonical Account and each real settlement/custody location a chain- or provider-specific Account Instance. AGW remains the root authorization and recovery surface. Each smart-account instance has its own address, nonce space, balances, permissions, delegates, mandates, and owner epoch. The current ordinary-vault interface is an obsolete scaffold proposal and must not be treated as the implementation target.
See the account and mirror product specification and AGW-owned programmable subaccounts for hierarchy, identity, Dinari compatibility gates, ownership rotation, AI grants, and chain-mirror invariants. Interface presence is not a security claim.
Bounded contexts
- Identity and eligibility
- Portfolios, Canonical Accounts, Account Instances, and mirrors
- Asset passports and provider resolution
- User-owned positions and valuations
- Strategy and basket definitions
- Automation mandates and execution intents
- Reconciliation and activity
- Protocol revenue and accretion
- Merchant catalog, attribution and advertiser permissions
- Reward obligations, funding, payouts and campaign reconciliation
- Provider income accrual, distribution and redemption
- Trails, groups, cosmetics, referrals and growth measurement
- Bundle plans, account bindings, position allocations, parent order intents and constituent order legs
The bundle order coordinator composes already-authorized provider actions and reserves cash/units per Account Instance. It tracks actual fills, remaining commitments, net proceeds and reconciliation by leg. A customer-defined multi-order plan is not an atomic cross-provider transaction. The customer must see partial completion and cannot be told a filled order was undone merely because another leg failed.
The account model keeps four ledgers explicit: provider books, chain balances, remote mirror policy state, and the Forage operational database. None is silently treated as authoritative for the others. Portfolios aggregate these ledgers for display; they do not hold or pool assets.
User yield and protocol accretion use separate ledgers. Any future Bearish AF relationship through published BURR burn events is a deferred proposal requiring separate review, not an established integration or a Forage dependency.
Reward liabilities add a distinct financial ledger. Mirror control records are not accounting balances. Discounts, pending commissions, received commissions, customer rewards, customer income and unrestricted protocol revenue cannot be combined as one earnings balance. BURR allocations are deferred until obligations, reserves and operating needs are covered; they cannot compete with already-promised rewards.
API rules
- Version every public route under
/v1. - Use schemas for validation and serialization.
- Accept caller-generated idempotency keys on external mutations.
- Persist a terminal status:
completed,failed,cancelled, orexpired. - Reconcile provider and chain state; do not infer completion from a submitted transaction alone.
- Return reference NAV and executable NAV separately.
- Expose issuer, provider, custody, rights, jurisdiction, and source timestamps alongside market data.
Deployment direction
forage.financeandapp.forage.finance: web edge deployment.api.forage.finance: independent Railway service using the repository root as monorepo context.- Railway PostgreSQL: private networking to API and workers.
- Background workers: separate Railway services with narrower credentials and independent scaling.