Source: https://www.hype-stack.dev/docs/development

# Development Overview

This section covers how to work with the Hype Stack codebase day-to-day: the folder structure, dev workflow, and key
concepts.

## Repo layout after `create`

**my-app** — bare template

- apps/
  - backend/ — Hono API, Prisma, Kysely, Valkey, S3 client
    - prisma/ — schema and migrations
    - src/features/ — domain modules (grows with packs)
    - src/routes/ — thin HTTP routers
    - src/jobs/ — cron jobs, empty until a pack adds one
    - src/queues/ — task queues for slow work, empty until a pack adds one
    - docker-compose.yml — Postgres, Valkey, RustFS
  - frontend/ — React 19, TanStack Router, Tailwind, HyperFetch, Electron
    - src/routes/ — file-based pages
    - src/features/ — UI modules
    - src/api/ — typed HyperFetch SDK
    - messages/en.json — Paraglide copy, packs merge into it
  - admin/ — operator app, a placeholder home until a starter fills it
  - mobile/ — Expo, expo-router, NativeWind
  - extension/ — browser extension, Vite, MV3
- packages/enums/ — shared enums both sides import
- stack.json — apps, installed packs, deploy records
- nx.json — task graph and caching
- pnpm-workspace.yaml — workspace package list

## After a SaaS starter pack

Installing a starter (the free Better Auth one, or a SaaS starter on Better Auth or WorkOS) adds, among other files:

**my-app** — + rows arrive with the starter

- apps/
  - admin/src/routes/ (added) — login, users, orgs, settings screens
  - backend/src/
    - features/auth/ (added) — login, sessions, password flows
    - features/organizations/ (added) — orgs, invitations, settings
    - middleware/auth/ (added) — withAuthUser, admin guards
    - middleware/permissions/ (added) — hasAccess + CASL
  - frontend/src/routes/
    - (private)/ (added) — auth-gated app shell
    - onboarding/ (added) — create or join an org
    - login/ (added) — sign-in screens

Feature packs (billing, teams, notifications, projects) add more modules under the same trees. See
[Authentication](/docs/backend/authentication) and [Organizations](/docs/backend/organizations).

## Dev loop

Start everything with one command:

```bash
pnpm dev
```

This runs every serve target through Nx with hot reload: the backend on port 3000, the frontend on port 4200, the admin
app and extension on their own Vite ports, and Metro for the mobile app.

## Where things live

| What              | Where                              |
| ----------------- | ---------------------------------- |
| API routes        | `apps/backend/src/routes/`         |
| Feature modules   | `apps/backend/src/features/`       |
| Database schema   | `apps/backend/prisma/schema/`      |
| Background jobs   | `apps/backend/src/jobs/index.ts`   |
| Task queues       | `apps/backend/src/queues/index.ts` |
| Translations      | `messages/en.json` in each app     |
| Frontend pages    | `apps/frontend/src/routes/`        |
| UI features       | `apps/frontend/src/features/`      |
| Shared components | `apps/frontend/src/components/`    |
| API client (SDK)  | `apps/frontend/src/api/`           |
| Theme tokens      | `apps/frontend/assets/styles.css`  |
| Env variables     | `.env` files in each app           |

## In this section

- [Commands](/docs/development/commands)
- [Monorepo](/docs/development/monorepo)
- [E2E typesafety](/docs/development/e2e-typesafety)
- [Observability](/docs/development/observability)
- [AI Overview](/docs/development/ai-overview)
- [Working with AI](/docs/development/working-with-ai)
- [Troubleshooting](/docs/development/troubleshooting)
- [Upgrading](/docs/development/upgrading)
- [Testing](/docs/development/testing)

The Expo app has its own page: [Mobile](/docs/mobile).