dwellops-platform/docs/development.md

Development guide

Prerequisites

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

Local setup

# 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

# 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

# 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

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

# 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

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.