Development Guide -Getting Started

The repo layout, the tech stack, and where a new developer should start.

Last updated Thu Jul 16 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

TL;DR -Social Live is a monorepo: one Flutter mobile app, one NestJS backend, a Next.js admin dashboard, and QA tooling, all in a single Git repository. This page is where a new engineer gets oriented.

Who this is for -Engineering (all levels). A new joiner should be able to read this page, clone the repo, and know where everything lives.

The mental model

Think of the codebase as four programs sharing one home:

The mobile app (lib/) is what users install. It's written in Flutter (Dart) and runs on iOS and Android.
The backend (backend/) is the brain. It holds all the business logic, the database, the realtime chat/room engine, and the live-video signaling. Every other program talks to it.
The admin dashboard (admin/) is an internal website operators use to manage users, read reports, watch revenue, and approve payouts. It never touches the database directly -it asks the backend.
Tooling (tools/) includes a live-room simulator so engineers can test streaming without picking up a phone.

If you remember one thing: the backend is the single source of truth. The mobile app and admin site are windows onto it.

Repository layout

social-live/
  lib/                  Flutter client (modules, core, shared, app shell)
  backend/              NestJS API + Prisma schema and migrations
  admin/                Next.js admin dashboard
  docs-portal/          This public documentation site
  tools/                Internal QA tooling (live-room simulator)
  docs/                 Planning documents (monetization, deployment, handoffs)
  test/                 Flutter tests (mirrors lib/ structure)
  android/ ios/         Platform shells for the Flutter app
  docker-compose.prod.yml   Production deployment definition
  scripts/              Deploy helpers

Path	Surface	Role
`lib/`	Flutter app	The end-user mobile client for iOS and Android
`backend/`	NestJS API	All business logic, persistence, realtime, and media signaling
`admin/`	Next.js dashboard	Operations: users, reports, revenue, withdrawals, docs
`tools/live-room-simulator/`	Next.js QA console	Drive live-room signaling and media without a phone

The tech stack

You don't need to know every library to start -but here's what's under the hood and why it's there.

Mobile client (`lib/`)

Technology	Version	Role
Flutter / Dart	SDK ^3.10	Cross-platform mobile UI
flutter_riverpod	3.x	State management and dependency injection
go_router	17.x	Declarative routing, composed from feature modules
flutter_webrtc	1.x	WebRTC peer connections for live media
mediasfu_mediasoup_client	0.1.x	mediasoup client-side SFU protocol
socket_io_client	3.x	Realtime signaling, chat, and presence
in_app_purchase (+ _android)	3.x / 0.5.x	StoreKit and Google Play Billing
flutter_secure_storage	10.x	Encrypted at-rest storage for auth tokens
cached_network_image	3.x	Image loading/caching

Backend (`backend/`)

Technology	Role
NestJS 10 (Express)	HTTP API framework, module system, DI
Prisma 6	ORM, schema, migrations for PostgreSQL
PostgreSQL 16	Primary datastore (users, rooms, ledger, everything)
Socket.IO	Realtime gateways: live rooms, chat, signaling
mediasoup	SFU (selective forwarding unit) for live video/audio
jsonwebtoken / @nestjs/jwt	Access + refresh token issuance and validation
class-validator	DTO validation with a global whitelist pipe
Twilio	SMS OTP delivery
Resend	Email OTP delivery
Apple App Store Server API	Server-side IAP verification (iOS)
Google Play Developer API	Server-side IAP verification + refunds (Android)
Stripe Connect	(Scaffolded) creator payout rails

Admin & tooling

Technology	Role
Next.js 15 (App Router, RSC)	Admin dashboard and this documentation
Recharts	Dashboard analytics charts
react-markdown + mermaid	Docs rendering with diagrams

Infrastructure

Piece	Role
Docker Compose	Production orchestration (containers on one VPS)
nginx + certbot	TLS termination and reverse proxy on the VPS
Named volumes	`postgres_data` (database), `uploads` (avatar images)

Notable choices and why

New developers ask "why is it built this way?" -the short answers:

Prisma + integer micros for money. Diamond values are stored as BigInt micros (millionths) so fractional credits never lose value to floating-point rounding. Coins are integers. (See Data model.)
Riverpod over BLoC. Providers live next to the features that own them; the module contract stays tiny (see Mobile app).
Socket.IO over raw WebSocket. Rooms, acknowledgements, and reconnection come free; the same client library runs in the Flutter app and the QA simulator.
mediasoup over peer-to-peer WebRTC. Rooms are one-to-many; an SFU keeps a host's upload bandwidth constant no matter how many viewers join.

Where to go next

Mobile app architecture -how the Flutter client is structured.
State & routing -Riverpod and GoRouter patterns.
Networking -how the app talks to the backend.
System architecture -the backend and how the surfaces connect.
Authentication -how login and sessions work.