# Mobile API Transformation Planning

This document details the step-by-step plan to prepare the Fermenty backend for Android/mobile app integration via API.

---

## Status (updated 2026-06-05)

Foundation is built and tested. See `00_PROJECT_OVERVIEW.md` §3/§5 for architecture.

**Done**
- [x] Auth: **Laravel Sanctum** token auth (chosen over JWT/Passport). `User` has `HasApiTokens`.
- [x] Routing: `api.fermenty.*` served under the stateless `api` middleware via `bootstrap/app.php`; versioned `/v1`.
- [x] CORS for `app.fermenty.*` origins (`config/cors.php`); `api` rate limiter.
- [x] Endpoints: `POST /v1/register`, `POST /v1/login`, `GET /v1/me`, `POST /v1/logout`, `GET /v1/dashboard`.
- [x] Error shape: standard Laravel `422 {message, errors}`; `401` when unauthenticated.

**Next**
- [ ] Batches vertical slice: `/v1/batches` (list/show/create + advance/skip/pause/resume/discard) reusing `BatchService` + `BatchPolicy`.
- [ ] Logs/measurements, catalogue (ferment types + guides), community, notifications, profile.
- [ ] Pagination/filtering conventions; consistent resource envelopes.
- [ ] Device-token registration endpoint + push provider (FCM) — see §5 below.
- [ ] Convert the `app.*` simulation to consume these endpoints over HTTP.

---

## 1. API Inventory & Documentation
- List all endpoints required for mobile (authentication, user profile, batches, logs, measurements, notifications, recipes, etc.)
- Document request/response formats for each endpoint
- Specify authentication headers and error response structure
- Maintain up-to-date API documentation (e.g., OpenAPI/Swagger, Postman collection, or Markdown)

## 2. Authentication & Security
- Select and configure secure API authentication (JWT, Laravel Sanctum, or Passport)
- Ensure endpoints require authentication where appropriate
- Set up CORS for mobile app domains
- Enforce HTTPS for all API traffic

## 3. API Feature Coverage
- Review all web features needed in the mobile app
- Ensure each feature is available via API (including premium gating and user plan checks)
- Add or refactor endpoints as needed for mobile workflows
- Document any differences between web and mobile flows

## 4. Testing & Versioning
- Test all endpoints with Postman or similar tools
- Write automated tests for critical API endpoints
- Consider introducing API versioning (e.g., /api/v1/) for future-proofing

## 5. Push Notification Readiness
- Plan for device token registration (endpoint to save device tokens per user)
- Choose a push provider (Firebase Cloud Messaging, OneSignal, etc.)
- Add backend logic to send push notifications via provider
- Document push notification payload formats

## 6. Mobile-Specific Considerations
- Implement pagination and filtering for large data sets
- Optimize endpoints for mobile (minimize payloads, support partial updates)
- Plan for offline support and sync (if needed)
- Standardize error and session management for mobile clients

---

## Next Steps
- Assign owners and deadlines for each step
- Track progress in this document or a project management tool
- Update documentation as the API evolves

---

Feel free to expand each section with technical details, endpoint lists, and implementation notes as you proceed.