Repository Structure

Current Layout

ais/
├── apps/
│   ├── backend/       # planned Spring Boot service
│   ├── mobile/        # planned production Flutter app
│   └── web/           # planned Next.js dashboard
├── docs/              # project-wide developer docs
└── reference/
    └── mobile_app_demo/ # current working Flutter POC

Target Layout

ais/
├── apps/
│   ├── backend/
│   ├── web/
│   └── mobile/
├── packages/
│   └── contracts/
│       ├── openapi.yaml
│       ├── generated-typescript/
│       └── generated-dart/
├── infra/
│   ├── compose.yaml
│   ├── docker/
│   └── deployment/
├── docs/
├── scripts/
├── AGENTS.md
├── Makefile
└── README.md

Ownership Rules

Path	Source of truth
`packages/contracts/openapi.yaml`	API operations, DTOs, validation, errors
`apps/backend`	Domain logic, persistence, authorization, migrations
`apps/web`	Browser workflows and admin/user UI
`apps/mobile`	Production mobile workflows
`reference/mobile_app_demo`	Existing Flutter POC behavior and reference implementation
`infra`	Local and deployment infrastructure
`docs`	Build, run, test, deploy, and maintenance guidance

Migration Rule

When moving POC behavior into apps/mobile, keep it as a deliberate port:

preserve event semantics;
replace hard-coded configuration with build-time config;
add generated API clients from OpenAPI;
add durable local state if offline reads are required;
add tests before replacing working behavior.