Architecture

WeWorks is a Yarn 4 + Turbo monorepo with separate deployable applications and shared packages.

Repository layout

weworks/
├── apps/
│   ├── api/          # Fastify API, Prisma, PostgreSQL
│   ├── client/       # Next.js 14 — main web app
│   ├── landing/      # Next.js 15 — public marketing site
│   └── docs/         # Nextra docs (this site)
├── packages/
│   ├── config/       # Shared ESLint config
│   └── tsconfig/     # Shared TypeScript config
├── docker-compose.yml
├── Dockerfile
└── INSTALL.md        # Extended server install guide

Tech stack

Layer	Technology
Frontend (client)	Next.js 14, React 18, Tailwind, shadcn/ui
Frontend (landing)	Next.js 15, Tailwind
Docs	Nextra 3, nextra-theme-docs
API	Fastify 4, TypeScript
Database	PostgreSQL 15, Prisma 5
Payments	Stripe
Auth	Session JWT/cookies, OAuth/OIDC/SAML

How apps communicate

Browser  →  Client (3001)  →  /api/v1/* proxy  →  API (5003)  →  PostgreSQL
Browser  →  Landing (3000)  →  public pages + links to client auth
Browser  →  Docs (3002)     →  static documentation

The client app proxies API requests through pages/api/v1/[...path].ts so the browser uses same-origin /api/v1 while the server forwards to the Fastify API.

API structure

apps/api/src/
├── controllers/    # Route handlers (tickets, auth, wallet, hardware, …)
├── lib/            # Auth, sessions, roles, email, notifications
├── prisma/         # Schema, migrations, seed
└── main.ts         # Server entry (port 5003)

Key domains: tickets, users, wallet/credit, hardware orders, tasker seeds, admin config, webhooks, email queues.

Client structure

apps/client/
├── pages/              # Next.js routes (issues, admin, hardware-shop, …)
├── components/         # UI components (CreateTicketForm, TaskerDashboard, …)
├── @/shadcn/           # shadcn/ui components and hooks
├── locales/*/weworks.json   # i18n strings
└── store/              # Session/user state

Production deployment (Docker Compose)

The root docker-compose.yml runs five services:

Service	Image	Host port
`weworks_postgres`	postgres:15-alpine	5432
`weworks_api`	ghcr.io/…/api	5003
`weworks_landing`	ghcr.io/…/landing	80 → 3000
`weworks_client`	ghcr.io/…/client	3001
`weworks_docs`	ghcr.io/…/docs	3002

Images are built via GitHub Actions and published to GHCR. The API container runs Prisma migrations and seed on startup.

Environment configuration

API: apps/api/.env — DATABASE_URL, SECRET, JWT_SECRET, STRIPE_SECRET_KEY, FRONTEND_URL
Client: apps/client/.env — API_URL, NEXT_PUBLIC_API_URL, Stripe publishable key
Copy from each app’s .env.example when setting up locally

Features Install with Docker