A React web client and an Expo mobile client in one NX monorepo, sharing one Redux core and one set of design tokens, with a 17-chapter guide that explains every decision: quality gates, design system, client observability, testing, release and rollback.
- One core for web and mobile: the Redux store, thunks, selectors, zod schemas and the API client live in
packages/core; each app passes in its storage, logger and config at startup. The UI is written per platform. Mobile Client - One set of design tokens, two outputs: Style Dictionary builds CSS variables for Tailwind and plain numbers for React Native. Design System
- Components are done when they are pinned: every Storybook story has a visual snapshot and an axe-core accessibility check in Playwright. Design System
- A trace ID from the browser to the backend logs: the client sends it as a header, so a user's error in Sentry leads to the matching API logs. Client Observability
- Optimistic updates with an explicit rollback in reducers. State Management
- Errors as a taxonomy: backend error codes mapped to user messages, toasts, retry and an error boundary. API Client and Errors
- Rollback without a rebuild: every release is kept in S3 as a versioned copy, and a manual workflow puts it back. Release and Deployment
- Tests at every level: unit tests with a real store, Playwright e2e with a mocked API, mobile screen tests on
jest-expo. Testing Strategy
This repository holds the clients. The API they talk to is in prod-forge/backend, the AWS infrastructure in prod-forge/terraform; the organization page has the architecture diagram and the reading order.
| Layer | Tools |
|---|---|
| Web Client | React · Vite · Redux Toolkit · Tailwind CSS · NX |
| Mobile Client | Expo · React Native · Redux Toolkit |
| Quality | ESLint · Prettier · Husky · Commitlint · Playwright · Storybook |
Requires Node 24 and the backend API running (see the backend guide).
npm ci
cp .env.example .env # VITE_API_BASE_URL is required for a build (absolute URL ending with "/"); dev falls back to the /api/v1/ proxy
npm run dev # web client
cp apps/mobile-client/.env.example apps/mobile-client/.env # EXPO_PUBLIC_API_BASE_URL, mobile client only
npm run dev:mobile # mobile client (Expo)- 1. Repository Strategy
- 2. Architecture Decisions
- 3. Development Workflow
- 4. AI-Assisted Development
- 5. Code Quality
- 6. Styles Management
- 7. Assets Management
- 8. Design System
- 9. State Management
- 10. API Client and Errors
- 11. Client Observability
- 12. Testing Strategy
- 13. Configuration
- 14. Performance
- 15. Security
- 16. Release and Deployment
- 17. Mobile Client
Full table of contents
- 4. AI-Assisted Development
- 8. Design System
A frontend is easy to start and hard to keep healthy.
The first screen takes an afternoon. What takes years is everything around it: two clients that must agree on the same rules, a bundle that grows a little with every feature, an error a user saw that nobody can reproduce, a release that has to be rolled back on a Friday evening, and a design that drifts a pixel at a time until nobody trusts it.
This repository is an attempt to show that work, not just the screens.
The stack - React, Expo, Redux Toolkit, Tailwind, NX - is not the point. These are just tools. The principles behind them apply to almost any client, whatever framework comes next.
What matters is the thinking:
- Why does sharing a store and an API layer between web and mobile pay off only with a strict dependency direction?
- Why should a design system live in the repository, with tokens, stories and visual tests, and not in a design file?
- Why does a client need its own observability when the backend already logs every request?
- Why is the browser an untrusted environment, and what does that change about tokens and configuration?
These are not advanced topics. They are basic requirements for any client that real users depend on. The goal of Prod Forge is to make these practices visible, understandable, and reusable.
Open work is tracked in the roadmap and summarized on the organization page.
The best time to set up these practices is at the beginning of a project.
The second best time is now.
A client without error tracking leaves you guessing about what users actually saw. A design system without visual tests drifts until nobody trusts it. A bundle without a budget only grows. A release without a rollback path turns a small mistake into an outage.
None of these things are difficult to set up. They are just easy to skip. This project exists as a reminder not to skip them.
- Passwords, refresh tokens, sign-up and an identity provider: the clients sign in with the backend's login stub, see Security
- Store release of the mobile app: no EAS Build, EAS Submit or over-the-air updates, see Mobile Client
- Running CI: the workflows exist but are disabled on purpose, see the roadmap
We welcome any kind of contribution, please read the guidelines:
