Tycoon is a multiplayer board game platform backed by smart contracts on Stellar (Soroban) and NEAR (wallet auth). This monorepo contains the game backend, frontend, shop microservice, and on-chain contracts.
┌────────────┐ HTTP / WS ┌────────────┐ HTTP (proxy) ┌──────────┐
│ │ ◄──────────────────────► │ │ ────────────────────► │ │
│ frontend │ │ backend │ │ shop-api │
│ (Next.js) │ │ (NestJS) │ │ (NestJS) │
└─────┬──────┘ └─────┬──────┘ └────┬─────┘
│ │ │
│ NEAR wallet │ PostgreSQL + Redis │ PostgreSQL
│ (wallet-selector) │ (tycoon_db) │ (shop db)
│ │ │
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌──────────┐
│ NEAR │ │ Redis │ │ Postgres │
│ testnet │ │ (cache) │ │ │
└────────────┘ └────────────┘ └──────────┘
┌────────────┐
│ contract/ │ Soroban smart contracts (Stellar)
│ │ Built with Rust + soroban-sdk v23
└────────────┘
| Package | Stack | Purpose |
|---|---|---|
frontend/ |
Next.js 16, React 19, Tailwind, Vitest, Playwright | Player-facing web app |
backend/ |
NestJS 11, TypeORM, PostgreSQL, Redis | Game API, auth, shop proxy |
shop-api/ |
NestJS 10, TypeORM, PostgreSQL | Authoritative purchase writes (idempotent) |
contract/ |
Rust, Soroban SDK v23 | On-chain game logic, tokens, collectibles |
tycoon-monorepo/
├── frontend/ # Next.js client (React 19)
├── backend/ # NestJS API server
│ └── docs/ # ADRs, runbooks, guides
├── shop-api/ # Shop microservice (purchases)
├── contract/ # Soroban smart contracts (Rust)
├── .github/workflows/ # CI pipelines
└── CONTRIBUTING.md # Setup & contribution guide
shop-api/— Shop microservice (NestJS)- Purchases API:
shop-api/src/purchases/(authoritative purchase writes) - Uses its own PostgreSQL database
- Docker:
shop-api/Dockerfile+shop-api/docker-compose.yml
- Purchases API:
See ADR-001 for the purchase write path architecture and docs/SHOP_ARCHITECTURE.md (ADR-003) for the field-by-field mapping between the two Purchase entities.
cd shop-api
docker compose up --buildThis starts:
| Service | Port | Notes |
|---|---|---|
shop-api |
3000 |
Non-root container; healthcheck on GET /health |
shop-postgres |
5433 (host) → 5432 (container) |
Isolated from the backend Postgres on 5432 |
Wait for docker compose ps to show shop-api as healthy, then:
curl http://localhost:3000/healthcd shop-api
npm install
cp .env.example .env # point DB_* at a local Postgres
npm run start:devSee shop-api/README.md for logging, cleanup jobs, and test instructions.
cd backend
docker compose up -d # Postgres + Redis + pgAdmin, ports 5432/6379/5050
npm install
npm run start:devCI runs on every PR via GitHub Actions:
| Workflow | What it checks |
|---|---|
| Backend CI | Build, test, migrations, admin guard verification |
| Frontend CI | Typecheck (tsc, fast-fail), build, bundle budget, lint, Vitest, Playwright E2E |
| Contract CI | Format, clippy, test, WASM build + size budget |
See CONTRIBUTING.md for the full contribution workflow, including branch naming, commit conventions, and per-package CI checks.
The frontend uses NEAR wallet exclusively (via @near-wallet-selector) until Stellar smart contracts are production-ready. See ADR-003 for the full rationale.
- Wallet provider:
frontend/src/components/providers/near-wallet-provider.tsx - Error handling:
frontend/src/lib/near/errors.ts - Telemetry:
frontend/src/lib/near/telemetry.ts(privacy-safe, no PII)
See CONTRIBUTING.md for setup instructions, workflow, and CI details.
Key links:
- CONTRIBUTING.md — setup, workflow, first-issue guide
- ADR-001 — purchase write path ownership
- ADR-003 — wallet strategy (NEAR-only)
- Admin Routes Matrix — admin guard coverage