Add OAS3 microservice specs and migration guide for monolith decomposition

[devin-ai-integration]

Summary

Adds comprehensive OpenAPI 3.0 specifications documenting how the FTGO monolith should be decomposed into four independent microservices, plus a migration guide. No application code is changed — this is purely documentation.

New files:

• api-specs/order-service.yaml — Order lifecycle, state transitions, async event contracts
• api-specs/consumer-service.yaml — Consumer registration, retrieval, order validation
• api-specs/restaurant-service.yaml — Restaurant/menu management, menu validation
• api-specs/courier-service.yaml — Courier management, availability, location, delivery planning
• api-specs/api-gateway.yaml — Aggregated routing + composite /orders/{orderId}/details endpoint
• MIGRATION_GUIDE.md — Service boundaries, data ownership, communication patterns, Strangler Fig migration sequence, database decomposition strategy

Each spec was derived by reading the existing controllers (OrderController, ConsumerController, RestaurantController, CourierController), service classes, domain entities, and API DTOs. Specs include both the endpoints that exist today and new inter-service communication endpoints proposed for the microservice architecture (e.g. POST /consumers/{id}/validate-order, GET /couriers/available, POST /couriers/{id}/actions).

Review & Testing Checklist for Human

• Verify spec-to-code accuracy for existing endpoints: Cross-check that path definitions, HTTP methods, request/response schemas in each spec match the actual Spring @RequestMapping annotations and DTO classes. Key files: OrderController.java (10 endpoints), ConsumerController.java (2 endpoints), RestaurantController.java (2 endpoints), CourierController.java (5 endpoints)
• Verify schema field accuracy: Confirm that OrderState enum values, Order/Consumer/Restaurant/Courier field names and types, and value objects (Money, Address, PersonName) match the actual JPA entities in ftgo-domain/
• Review proposed inter-service endpoints: Several endpoints in the specs don't exist in the monolith today and are proposed for the microservice architecture — verify these make sense for the decomposition (e.g. consumer validation endpoint, menu validation endpoint, courier available/actions endpoints, gateway composite endpoint)
• Review migration guide phasing: Validate that the extraction order (Consumer → Restaurant → Courier → Order) and the Saga pattern for distributed createOrder() are sound for this codebase's dependency graph

Test plan: These are YAML documentation files with no runtime impact. Optionally validate the specs with an OpenAPI linter (e.g. npx @redocly/cli lint api-specs/*.yaml) to catch structural issues.

Notes

• Common schemas (Money, Address, PersonName, ErrorResponse) are duplicated across specs — this is intentional since each microservice spec should be self-contained
• The YAML specs are not validated by CI; consider adding an OpenAPI linter step if these specs will be maintained long-term
• The TicketController in the monolith is currently empty (no endpoints) so it was not given a dedicated spec; ticket-related state transitions are covered under the Order Service

Link to Devin session: https://app.devin.ai/sessions/d3d2e441b6fa4239ae6a00d5754d05ab
Requested by: @achalc

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring