Development Workflow

Use a contract-first modular monorepo and deliver one vertical slice at a time.

Delivery Sequence

Feature definition
-> OpenAPI contract
-> Database migration
-> Backend implementation and tests
-> Generated clients
-> Next.js flow
-> Flutter flow
-> Cross-platform E2E tests
-> Review and merge

Rules

• Design the API once in packages/contracts/openapi.yaml.
• Generate TypeScript and Dart clients; do not hand-write duplicate API models.
• Keep persistence entities separate from API DTOs.
• Keep generated files in clearly named directories.
• CI must regenerate clients and fail if committed generated output differs.
• Use API versioning, preferably /api/v1.
• Use ISO 8601 UTC timestamps.
• Use strings for UUIDs and decimal money values when precision matters.
• Define nullability, pagination, sorting, filters, enums, file limits, and errors in OpenAPI.

Standard Task Packet

Every implementation task should state:

• goal;
• allowed directories;
• source of truth;
• constraints;
• required tests;
• forbidden changes;
• definition of done;
• expected output.

Branching

Use short-lived branches or worktrees by vertical slice:

contract/asset-receiving
backend/asset-receiving
web/asset-receiving
mobile/asset-receiving
integration/asset-receiving

Foundation Checklist

• Pin Java, Node.js, package manager, Flutter, and Dart versions.
• Add root README.md, .editorconfig, .gitignore, and environment templates.
• Create packages/contracts/openapi.yaml.
• Add OpenAPI linting and breaking-change checks.
• Configure Spring, TypeScript, and Dart client generation.
• Add make generate-clients.
• Create infra/compose.yaml for PostgreSQL and required services.
• Define local, test, staging, and production configuration boundaries.
• Define logging, trace IDs, metrics, and health checks.