Ways of working
Tools
The toolchain of both repositories with versions and purpose, the services the team uses, and the commands everyone runs every day.
Versions are pinned in the repositories (.nvmrc, packageManager, pnpm-workspace.yaml catalog, pubspec.yaml). When this table and a repository disagree, the repository wins and this table is fixed.
Toolchain — hoco
| Tool | Version | Purpose | Notes |
|---|---|---|---|
| Node.js | 22 LTS (.nvmrc) | Runtime for everything in hoco | engines.node >=22 |
| pnpm | 11.13.1 (packageManager) | Workspaces and the dependency catalog | corepack enable picks the pinned version |
| Turborepo | 2.11 | Task runner and cache | turbo.json |
| TypeScript | 6.0.3 | Types | pnpm check-types |
| Biome | 2.5.15 | Lint and format (tabs, double quotes, LF) | pnpm check writes fixes, pnpm lint only checks; CI runs biome ci |
| lefthook | 2.2 | Git hooks | Installed by pnpm install (hooks) |
| commitlint | 21, config-conventional | Commit messages | Header at most 100 characters |
| gitleaks | Latest | Secret scanning | Optional locally (the hook skips it), enforced in CI |
| Vitest | 4.1 | Unit tests | pnpm test |
| Docker Desktop + Compose v2 | Current | Local services, image builds | WSL 2 backend on Windows |
| PostgreSQL 17, Redis 7, MinIO, Mailpit | Compose images | Local database, queues, object storage, e-mail catcher | Ports 5442, 6390, 9100/9101, 1125/8125 |
| Prisma + Prisma Studio | 7.10 | Schema, migrations, client; data browser | pnpm db:studio |
| Express · oRPC · Zod | 5 · 1.15 · 4.6 | HTTP server · contract and OpenAPI · schemas | ADR-002 |
| Scalar API reference | @scalar/hono-api-reference 0.12 | Human reference at /reference (local, staging, pre-production) | Disabled in production |
| Prism | @stoplight/prism-cli 5, through npx | Mock server from the OpenAPI document | Mock server |
| oasdiff | Latest, in CI | Breaking-change detection between contract versions | Added with SRV-03 |
| Next.js · React · Tailwind CSS · next-intl · TanStack Query | 16.4 · 19.3 · 4.3 · 4.14 · 5.104 | Back-office and reseller web | |
| pino | 10 | Structured logs | LOG_LEVEL in .env |
| tsx · tsdown | 4.23 · 0.23 | Server dev mode · server build | |
| Fumadocs | 16 | This site | ADR-012 |
GitHub CLI (gh) | Current | PRs and issues from the terminal | Optional |
Toolchain — hoco-mobile
Set up by Imad in MOB-01; this table is updated when the repository exists.
| Tool | Version | Purpose | Notes |
|---|---|---|---|
| Flutter | Stable, exact version pinned in the repository (FVM, .fvmrc) and in CI | Both apps | Everyone runs the same version |
| Dart | Bundled with Flutter (3.6 or later for pub workspaces) | Language, pub workspace | |
| Melos | 7 | Scripts across the packages | Configured in the root pubspec.yaml |
| Android Studio, Android SDK, JDK 17 | Latest stable | Builds, emulators | An emulator image plus the reference mid-range phone for performance and outdoor checks |
| build_runner (freezed, json_serializable, drift) | Per pubspec.yaml | Code generation | Outputs committed |
| OpenAPI to Dart generator | Chosen in MOB-03 | hoco_api | Regenerated from the pinned document only |
| Firebase CLI and FlutterFire CLI | Latest | FCM configuration, App Distribution uploads | Projects dev, staging, prod |
| lefthook + commitlint | As in hoco | Hooks | Needs Node.js for commitlint |
| Xcode | Latest stable, on macOS | iOS builds | Only if iOS is confirmed (D-10) |
Services
| Service | Used for | Accounts |
|---|---|---|
| GitHub — repositories, Actions, issues, Discussions | Code, CI, bugs, meeting notes | Access |
| GitHub Projects (optional) | A board view of the work — see below | Team |
| Claude Design | Design, prototypes, handoff (shared link + exported design bundle), HOCO's comments on review pages | Team (Akram) |
| Dokploy | Deploys the server, back-office and reseller web on the VPS (Traefik, TLS) | Accounts |
| VPS (Dokploy, later) | This site, restricted to the team and HOCO | Team (Anis) |
| Firebase | Push notifications (FCM), App Distribution | HOCO |
| Google Play Console | Internal, closed and production tracks | HOCO (organisation account) |
| Sentry | Error tracking for the apps and the server | HOCO |
| Uptime monitor | External checks of /health | Team |
| Password manager | Every secret and account credential | Shared vault "HOCO" |
| WhatsApp · Google Meet · e-mail | Communication (channels) | — |
GitHub Projects (optional)
The board is a view, never the plan. If the team uses one:
- One project, "HOCO delivery", across both repositories; its items are issues and PRs.
- Every item title starts with the task id:
SRV-14 — CRM module. - Fields: Task ID, Phase (P0…P4), Owner, Status (Todo · In progress · In review · Done). No date fields — dates come from the scheduler.
tasks.jsonstays the plan of record. A task never exists only on the board; a task added to the plan gets its board item, not the other way round.
Commands — hoco
First setup:
corepack enable # pnpm at the version pinned in package.json
git clone git@github.com:AnisBetehi/hoco.git && cd hoco
pnpm install # dependencies, Prisma client, git hooks
cp .env.example .env # one file for every app, values match docker compose
pnpm db:start # Postgres, Redis, MinIO, Mailpit
pnpm db:migrate # apply the migrations to the local databaseEvery day:
pnpm dev # server :3100, dashboard :3101, web :3102
pnpm dev:server # or one app: dev:dashboard, dev:web, dev:docs (:3103)
pnpm db:studio # browse the local database
pnpm db:stop # stop the services (pnpm db:down also removes the containers)Before pushing (CI runs the same):
pnpm check # Biome, with fixes
pnpm check-types
pnpm test
pnpm build # also compiles every docs pageContract, database, docs and plan:
pnpm openapi:export # writes apps/docs/public/openapi/hoco-v1.json
npx @stoplight/prism-cli mock apps/docs/public/openapi/hoco-v1.json --port 4010
pnpm --filter @hoco/db exec prisma migrate dev --name srv14_crm_core
pnpm --filter @hoco/docs schedule # print the calendar computed from tasks.json
pnpm docs:generate # regenerate the team-task pages
pnpm --filter @hoco/docs check-mdx # compile-check every MDX pageCommands — hoco-mobile
Assumption — the script names are fixed in MOB-01 and MOB-03; this block is updated then.
fvm install && fvm use # the pinned Flutter version
dart pub get # resolves the whole pub workspace
melos run generate # build_runner in every package
melos run api:generate # regenerate hoco_api from the pinned hoco-v1.json
melos run analyze # dart format check + flutter analyze
melos run test
cd apps/delegate && flutter run --flavor staging -t lib/main_staging.dart
flutter build appbundle --flavor prod -t lib/main_prod.dart --build-name 1.0.0 --build-number 42Windows notes
The team works on Windows; Git Bash and PowerShell both run the scripts above.
git config --global core.autocrlf input— the repositories are LF (.gitattributes), Biome formats LF.git config --global core.longpaths true— avoids path-length errors innode_modulesand Gradle caches.- Docker Desktop with the WSL 2 backend.
- The local ports (3100–3103, 5442, 6390, 9100, 9101, 1125, 8125) were chosen to coexist with other projects: keep them free.
Change requests and decisions
The cahier's scope clause turned into a process: what counts as a change, how a request becomes a written decision, how the plan is updated, how the decision register works, and when HOCO signs.
Product requirements (PRD)
Why the HOCO B2B ecosystem is built, for whom and in which release — goals, personas, user stories with acceptance criteria, scope boundaries, risks and success metrics.