Web App Scaffold

1. Project Setup & Environment

Scaffold: Vite + React + TypeScript template.

Node: lock LTS (e.g. v18.x) with .nvmrc.

Env vars: only VITE_* in .env.example (API_URL, POSTHOG_KEY, SENTRY_DSN, FEATURE_FLAG_URL); real .env.* git‑ignored.

Config module: src/config/index.ts exports typed import.meta.env values.

Branching: protected main/release; feature branches; GitFlow or trunk‑based.

2. Core Dependencies & Tools

Styling: Tailwind CSS JIT + PostCSS, Autoprefixer, @tailwindcss/forms/typography, Heroicons, Headless UI, clsx/CVA.

Data & Validation: React Query, axios (or ky) with interceptors, Zod, React Hook Form + Zod resolver.

Routing: React Router v6 with nested layouts.

Feature Flags & Analytics: posthog-js.

Charts & Tables: Recharts or Chart.js, React Table or TanStack Table.

Notifications: react-toastify or notistack.

Testing: Vitest + RTL + MSW (unit/integration), Playwright (E2E), Chromatic (visual).

Quality: ESLint (+ TS, React, a11y, import/order, tailwindcss plugin), Prettier + prettier-plugin-tailwindcss, Stylelint (if CSS).

Scaffolding: Plop generators for components/pages/hooks.

CI/CD & Security: GitHub Actions, semantic-release, Dependabot/Snyk, Lighthouse CI, vite-plugin-visualizer, vite-plugin-compression, Sentry.

3. Folder Structure (Large Fintech App)

├── .github/              # workflows: lint, test, build, storybook, analyze, security scans
├── .husky/               # Git hooks
├── .storybook/           # Storybook config & MSW addon
├── public/               # favicons, robots.txt, static images
├── scripts/              # custom scripts (e.g. svg→React)
├── src/
│   ├── assets/           # raw images/fonts/icons
│   ├── config/           # typed env + feature-flag wiring
│   │   └── index.ts
│   ├── styles/           # Tailwind entry, tokens & overrides
│   │   ├── globals.css
│   │   ├── tailwind.config.ts
│   │   └── tokens.ts
│   ├── utils/            # pure helpers (date, currency, debounce)
│   ├── hooks/            # generic hooks (useWebVitals, useFeatureFlag)
│   ├── services/         # API layer + validation
│   │   ├── api.ts        # axios instance + interceptors
│   │   ├── schemas/      # Zod schemas per resource
│   │   └── hooks/        # React Query hooks
│   ├── store/            # optional global state (Zustand or Redux Toolkit)
│   ├── components/       # presentational (Atomic)
│   │   ├── atoms/        # Button, Input, Icon, Spinner
│   │   ├── molecules/    # FormField, Card, Tooltip
│   │   ├── organisms/    # DataList, Modal, Navbar
│   │   └── templates/    # Layouts (AuthLayout, DashboardLayout)
│   ├── containers/       # stateful pages (LoginPage, DashboardPage)
│   ├── features/         # domain modules (Auth, Accounts, Transfers)
│   ├── locales/          # i18n resources (en/, sw/, etc.)
│   ├── App.tsx           # root with Router & Providers
│   └── main.tsx          # bootstrap QueryClient, PostHog, WebVitals
├── cypress/ or playwright/ # E2E specs mirroring containers
├── plopfile.js           # scaffold generators
├── tsconfig.json         # strict + path aliases (@/* → src/*)
├── vite.config.ts        # Vite plugins (React, Tailwind, visualizer, compression)
├── package.json          # scripts & deps
└── README.md             # setup, scripts, folder conventions, smoke tests

4. Routing Architecture

React Router v6 with nested <Routes> under layouts:

/auth/* → AuthLayout

/auth/login, /auth/register, /auth/forgot-password, /auth/mfa

/app/* → DashboardLayout (protected)

/app/home, /app/accounts, /app/accounts/:accountId,

/app/transactions, /app/transactions/:txId,

/app/transfer, /app/transfer/confirm,

/app/kyc, /app/settings, /app/support

* → NotFoundPage

Route Guards via a <ProtectedRoute> wrapper that checks auth & KYC status.

Code splitting: lazy‑load each route component with React.lazy + Suspense fallback spinner.

Feature‑flagged routes: hide/redirect based on posthog.isFeatureEnabled.

5. API Integration & Sample Flow

axios instance: baseURL from config, adds auth token (cookie or header), intercepts 401 → refresh flow.

Zod schemas in services/schemas/ (e.g. account.ts, transaction.ts).

React Query hooks in services/hooks/:

useAccounts(), useAccount(accountId), useTransactions(), useTransfer()

Mutations with optimistic updates & invalidateQueries.

Error mapping: throw domain‑specific errors (e.g. InsufficientFundsError) surfaced to UI.

6. Authentication & Authorization

JWT flows with refresh tokens in httpOnly cookies.

Multi‑factor Auth: /auth/mfa page, code input, resend.

Role‑based UI: hide admin/features via flags or user.role.

Global Auth Context: exposes user, isAuthenticated, logout().

7. Feature Flags & Analytics

PostHog init in main.tsx, key from config.

Feature wrapper component for toggling UI/features.

Analytics util: track(event, props) to unify naming and batching.

Session replay & heatmaps enabled in production flags as needed.

8. Forms & KYC Workflows

React Hook Form + Zod for all forms (login, register, transfer, KYC).

File uploads: React Dropzone + direct S3 uploads via presigned URLs (service in services/api.ts).

Form steps: multi‑step KYC wizard with progress indicator.

Accessible: error messages, aria‑labels, keyboard nav.

9. Component Architecture & Design System

Atomic Design enforced by folder.

Tailwind Utility Classes via JIT; clsx for conditional classNames.

CVA for component variants (e.g. button sizes/colors).

Theme toggling: light/dark via CSS variables and Tailwind dark:.

Storybook: stories for every atom/molecule/organism with MSW mocks and Chromatic integration for visual regression.

10. Performance Optimization

Code splitting at route & heavy component level.

Tailwind Purging: production build removes unused classes.

Compression: gzip/Brotli via vite-plugin-compression.

Image optimization: vite-imagetools or external CDN.

Web Vitals: capture LCP, FID, CLS and send to PostHog.

Bundle budgets: enforce max sizes in CI via vite-plugin-visualizer.

11. Security Best Practices

CSP & SRI: inject policies via vite-plugin-html.

HTTP‑only cookies for tokens, SameSite=Strict.

Dependency scanning: Dependabot/Snyk; npm audit in CI.

Sanitization: use DOMPurify for any rich text.

No inline JS/CSS: all logic & styles compiled.

12. Testing Strategy

Unit: Vitest for utils, hooks, small components.

Integration: RTL + MSW for data‑driven and form flows.

E2E: Playwright (or Cypress) for key user journeys (login, transfer, KYC).

Visual: Chromatic snapshot tests.

Coverage: ≥ 80% lines, ≥ 70% branches; enforce in CI.

13. CI/CD & Release

GitHub Actions steps on PR:

install & type‑check

lint & stylelint

unit/integration tests + coverage

E2E tests headless

build app & storybook

bundle & Lighthouse CI (fail on regressions)

dependency scan

semantic-release: automated versioning & changelog.

Storybook deploy: Netlify/Vercel on main.

14. Monitoring & Observability

PostHog: feature flags, event capture, session replay.

Sentry: uncaught errors via global Error Boundary.

React Query Devtools in dev; capture query timings in prod.

Custom dashboards: monitor API latency, error rates, user flows.

15. Developer Experience & Onboarding

README.md: clear setup, scripts, conventions, scaffold guide, smoke tests.

.vscode: extensions.json (Tailwind CSS IntelliSense, ESLint, Prettier, GitLens); settings.json (formatOnSave, import sorting).

Plop: generate atoms/molecules/organisms/pages with TSX, Tailwind stub, Storybook, test file.

Smoke tests (must pass out‑of‑the‑box):

1. Project Setup & Environment#

2. Core Dependencies & Tools#

3. Folder Structure (Large Fintech App)#

4. Routing Architecture#

5. API Integration & Sample Flow#

6. Authentication & Authorization#

7. Feature Flags & Analytics#

8. Forms & KYC Workflows#

9. Component Architecture & Design System#

10. Performance Optimization#

11. Security Best Practices#

12. Testing Strategy#

13. CI/CD & Release#

14. Monitoring & Observability#

15. Developer Experience & Onboarding#