Repository layout
A Turborepo + pnpm monorepo. Deployable things live in apps/, shared libraries in packages/, and the Solidity project in contracts/.
axon-mvp/
├─ apps/
│ ├─ web/ # Main Next.js web/desktop app (port 4300)
│ ├─ admin/ # Admin console (Next.js, port 4200)
│ ├─ mobile-version/ # React screen + hook library reused by web
│ │
│ ├─ api-gateway/ # Public entry point — auth, routing, rate-limit (port 3000)
│ ├─ service-auth/ # SIWE login, JWT, refresh tokens (3001)
│ ├─ service-kyc/ # Sumsub KYC/KYB
│ ├─ service-wallet/ # Balance & network reads
│ ├─ service-transactions/ # Sends, top-ups, history
│ ├─ service-agreements/ # Milestone escrow lifecycle + notifications
│ ├─ service-distributions/ # Batch payout planner & routing
│ ├─ service-settlements/ # Hash-chained ledger + anchoring (3 workers)
│ ├─ service-funding/ # Instant Funding (coverage watcher + sweeper)
│ ├─ service-onramp/ # Fiat on/off-ramp provider pool
│ ├─ service-ai/ # AI assistant (OpenAI)
│ ├─ service-admin/ # Ops plane (facilities, policies, alerts)
│ ├─ service-reconciliation/ # Background reconciler (routes + escrow)
│ │
│ └─ shell/, mfe-*/ # Legacy module-federation MFEs (behind the
│ # 'legacy-mfe' compose profile — not in the
│ # default build; superseded by apps/web)
│
├─ packages/
│ ├─ db/ # Prisma schema, migrations, generated @axon/db client,
│ │ # money.ts (BigInt money math), backfills/
│ ├─ integration-layer/ # Vendor adapters: ai, sumsub, onramper, ramps/,
│ │ # custody/ (escrow + Circle), blockchain, base
│ ├─ shared-config/ # env.config.ts (all config), auth.util.ts (JWT verify),
│ │ # service ports/hosts, fail-closed getSecret()
│ ├─ shared-types/ # Cross-service TypeScript types
│ ├─ shared-ui/ # Shared React UI (icons, primitives)
│ └─ shared-reports/ # PDF/CSV report builders
│
├─ contracts/ # Hardhat project
│ ├─ src/AXONEscrow.sol # milestone escrow
│ ├─ src/MockUSDC.sol # testnet USDC
│ ├─ scripts/deploy.ts # deployment (supports FEE_RECIPIENT/OWNER_AFTER_DEPLOY)
│ └─ test/ # contract tests
│
├─ docs/ # This GitBook + internal design notes
├─ scripts/ # health-check.sh, infra-check.sh, ops scripts
├─ docker-compose.yml # Base stack (network, db, redis, all services)
├─ docker-compose.prod.yml # Prod overlay (web, admin, caddy, build args)
├─ Dockerfile.backend # Generic NestJS service image
├─ Dockerfile.frontend # Generic Next.js app image
├─ turbo.json # Turborepo task graph
└─ pnpm-workspace.yaml
Anatomy of a backend service
Every apps/service-* is a standard NestJS app:
service-funding/
├─ src/
│ ├─ main.ts # bootstrap (global prefix /api/v1, port)
│ ├─ app.module.ts # module wiring
│ └─ funding/
│ ├─ funding.controller.ts # HTTP endpoints (@Get/@Post …)
│ ├─ funding.service.ts # business logic
│ ├─ coverage.watcher.ts # background worker (30s)
│ ├─ collection-sweeper.ts # on-chain sweep
│ └─ *.ts # clients, helpers, types
├─ package.json
└─ tsconfig.json
Controllers map to /(api/v1)/<service>/…; services hold the logic; *.watcher.ts / *.worker.ts / *.sweeper.ts / *.reconciler.ts are background loops started from the module's onModuleInit.
Anatomy of the web app
web/src/
├─ app/ # Next.js App Router
│ ├─ (auth)/ # sign-in / sign-up
│ ├─ (reused)/ # screens reused from mobile-version
│ └─ (web)/ # bespoke desktop views (overview, custody, …)
├─ components/ # desktop views, dashboard, auth (Providers/AuthGate)
├─ hooks/ # usePrivyWagmiSync, useDashboardData, …
├─ lib/ # api clients (funding-api, settlements-api, …), wagmi.config
└─ store/ # Zustand stores (auth, mode/profile, …)