# Development guide

## Prerequisites

- **Node.js** ≥ 24
- **pnpm** ≥ 10 (`npm install -g pnpm@10`)
- **Docker** (for local infrastructure)

## Local setup

```bash
# 1. Clone the repository
git clone git@git.mifi.dev:mifi-ventures/dwellops-platform.git
cd dwellops-platform

# 2. Copy environment files
cp .env.example .env
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env

# 3. Start local services (Postgres + Mailpit)
docker compose up -d

# 4. Install all workspace dependencies
pnpm install

# 5. Generate Prisma client
pnpm db:generate

# 6. Run initial migration
pnpm db:migrate:dev

# 7. (Optional) Seed with dev data
pnpm db:seed

# 8. Start dev servers
pnpm dev
```

## Dev Container (VS Code / GitHub Codespaces)

Open the repository in VS Code and click **Reopen in Container** when prompted,
or run the command palette → `Dev Containers: Reopen in Container`.

The container starts Postgres and Mailpit via Docker Compose.
On first create, `pnpm install` and `pnpm db:generate` run automatically.

All ports are forwarded: see `.devcontainer/devcontainer.json` for the full list.

## Running tests

```bash
# Unit + integration tests (all workspaces)
pnpm test

# Watch mode
pnpm --filter @dwellops/api test:watch
pnpm --filter @dwellops/web test:watch

# End-to-end tests (requires the web app to be running)
pnpm test:e2e

# Coverage report
pnpm --filter @dwellops/api test -- --coverage
```

## Storybook

```bash
# Run Storybook for the web app (includes packages/ui stories)
pnpm --filter @dwellops/web storybook

# Run Storybook for the UI package standalone
pnpm --filter @dwellops/ui storybook
```

## Database operations

```bash
pnpm db:generate       # Re-generate Prisma client after schema changes
pnpm db:migrate:dev    # Create and apply a migration (dev only)
pnpm db:migrate        # Deploy pending migrations (CI/production)
pnpm db:push           # Push schema changes without a migration (prototype only)
pnpm db:studio         # Open Prisma Studio in the browser
pnpm db:seed           # Seed the database with dev data
```

## i18n

```bash
# Aggregate component translations.json files into messages/<locale>.json
pnpm i18n:aggregate
```

Add new strings by editing `translations.json` files alongside components,
then running `pnpm i18n:aggregate`. Never hand-edit `messages/en.json`
for component-specific strings.

## Code quality

```bash
pnpm lint          # ESLint + Stylelint
pnpm lint:fix      # Auto-fix lint issues
pnpm typecheck     # TypeScript across all workspaces
pnpm format        # Prettier
pnpm format:check  # Check formatting without writing
```

Pre-commit hooks run lint-staged automatically.

## Adding a new package

1. Create `packages/<name>/` with `package.json`, `tsconfig.json`, and `src/index.ts`.
2. Name the package `@dwellops/<name>`.
3. Extend `@dwellops/config/tsconfig/base.json` (or `node.json` / `react-library.json`).
4. Add a `workspace:*` reference in any consumer's `package.json`.
5. Add to root `tsconfig.json` references.
6. Run `pnpm install`.

## Adding a new route in apps/api

1. Create `src/modules/<feature>/<feature>.routes.ts`.
2. Implement thin route handlers — call services for business logic.
3. Register the routes in `src/app.ts`.
4. Write `<feature>.test.ts` alongside the routes.
5. Update Swagger schemas as part of the change.

## Adding a new page in apps/web

1. Create `src/app/[locale]/<path>/page.tsx` — thin page that delegates to a view.
2. Create `src/views/<FeatureName>View/` with the view component.
3. Create any new components in `src/components/` or `src/widgets/`.
4. Add translations to `translations.json` alongside each component.
5. Run `pnpm i18n:aggregate`.
6. Add Storybook stories for any new components/widgets.