# SOT Platform — Production Build Plan

Aligned with OneDrive workspace `010_Stock ownership Transfeer/` and **Pre-Development Readiness Review (2026-07-14)**.

## Stack (Architecture v1.0 + DevOps v01)

| Layer | Technology | Status |
|-------|------------|--------|
| Web | **Next.js 14** (App Router, RTL, AR/EN) | **In progress** — `apps/web` |
| API | NestJS 10 modular monolith | Next — `apps/api` |
| Database | PostgreSQL 15 + Flyway | Next — `db/migrations` |
| Queue/cache | Redis (BullMQ) | With API |
| Hosting | Alibaba Cloud KSA (Riyadh) | `infra/` (Terraform) |
| Integrations | MOCK → SANDBOX → LIVE | `@sot/shared/integration` |

## Repo layout

```
SOT-demo/
├── src/                    # Legacy Vite demo (reference UI — will be ported then retired)
└── platform/               # Production monorepo ← active development
    ├── apps/web/           # Next.js 14
    ├── apps/api/           # NestJS (next branch)
    ├── packages/shared/    # Types, OpenAPI, integration config
    ├── db/migrations/      # Flyway
    └── infra/              # Terraform Alibaba KSA
```

## Phase order (from project docs)

### Phase 1 — Web foundation (current branch)
- [x] Next.js 14 scaffold with Numu theme + RTL/i18n
- [x] `@sot/shared` types + OpenAPI spec copy
- [x] Route shells: `/auth`, `/seller`, `/company/approval`
- [x] API client pointed at `http://localhost:3000/v1`
- [ ] Port demo pages into Next.js (KYB, transfer, signing, escrow, MoCI)
- [ ] Auth session (JWT from NestJS when API lands)

### Phase 2 — API + database (next branch: `feat/nestjs-api-scaffold`)
Per readiness review §3 “Needed shortly after”:
1. NestJS 10 in `apps/api` — Auth, Users, Companies, Transfers modules
2. Flyway `V001__init.sql` from Database Schema v1.1
3. MOCK adapters (Nafath, Wathq, Moyasar, emdha, 4Jawaly) with `INTEGRATION_MODE`
4. OpenAPI implementation from `packages/shared/openapi/sot-api-v1.yaml`

### Phase 3 — Staging infra (branch: `infra/staging-alibaba-ksa`)
Per `Infrastructure-and-DevOps-Alibaba-KSA-v01.md`:
- Terraform: VPC, RDS, Redis, OSS, KMS, SAE/ACK, SLB, WAF
- CI/CD: lint → test → build image → Flyway migrate → deploy staging

### Phase 4 — CMA sandbox go-live
- Live vendor credentials, pen test (NCA ECC-2), legal doc sign-off

## Decisions to log (OneDrive Decision-Log)

1. **Cloud = Alibaba KSA** (DEC-005) — authoritative in DevOps doc
2. **Storage = OSS** (DEC-004)
3. **eSign = emdha** (PRD hint — confirm)
4. **CI/CD platform** — Yunxiao vs GitHub Actions + in-KSA runner

## Local development

```bash
# Production web (Next.js) — port 3001
cd platform && npm install && npm run dev:web

# Legacy Vite demo — port 5173 (reference until port complete)
cd .. && npm run dev
```

## API contract

Source of truth: `packages/shared/openapi/sot-api-v1.yaml` (copied from OneDrive `SOT_API_Spec_v01.yaml`).

Local server target: `http://localhost:3000/v1` (NestJS, Phase 2).