Initial commit

2026-03-10 21:30:52 -03:00
commit 72a4f0be26
145 changed files with 14881 additions and 0 deletions
--- a/docs/development.md
+++ b/docs/development.md
@@ -0,0 +1,135 @@
+# 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.