Imported from danfordChris/pesa-landing (AGENTS.md). Install upstream with npx skills add danfordChris/pesa-landing. Copyright stays with the author.

AGENTS.md

Scope

• This guide covers the repo root (backend/, backoffice/, mobile/, api/).
• Mobile has extra rules in mobile/AGENTS.md; follow both when editing Flutter code.

System Map (what talks to what)

• Runtime topology is defined in docker-compose.yml: postgres + redis + kafka/zookeeper + backend + backoffice.
• Backend is a Spring Boot monolith in backend/src/main/java/com/pesa/* with module boundaries by package (auth, user, loan, payment, admin, accounting, scheduler).
• API base is /api/v1 from backend/src/main/resources/application.yml; controllers use paths like /auth, /loans, /admin.
• Backoffice (backoffice/) is a Vite React SPA served by nginx; backoffice/nginx.conf proxies /api to http://backend:8080.
• Backoffice API client uses baseURL: '/api/v1' in backoffice/src/services/api.ts and expects backend envelope response.data.data.
• Mobile uses singleton ApiClient in mobile/lib/core/network/api_client.dart; default base URL is http://10.0.2.2:8080/api/v1 (Android emulator).

Core Business Flow (cross-component)

• User flow is encoded in api/*.http: register/login (api/auth.http) -> set PIN + KYC (api/users.http) -> apply/accept loan (api/loans.http) -> repay (api/payments.http).
• Admin flow runs through api/admin.http and backend/src/main/java/com/pesa/admin/controller/AdminController.java (loan decisions, product rates, customer controls, accounting views).
• Daily finance behavior is scheduled in backend/src/main/java/com/pesa/scheduler/LoanScheduler.java (interest accrual + IFRS9 stage/provision updates in EAT timezone).

Dev Workflows That Matter

• Full stack (preferred): docker compose up --build -d from repo root; verify API via /api/v1/actuator/health.
• Backend local: run from backend/ with mvn spring-boot:run; tests use H2 profile (@ActiveProfiles("test")) as shown in backend/src/test/java/com/pesa/integration/LoanFlowIntegrationTest.java.
• Backoffice local: from backoffice/ run npm install, then npm run dev (port 3001).
• Mobile local: from mobile/ run flutter pub get, flutter run; override API with --dart-define=API_BASE_URL=http://<host>:8080/api/v1 for physical devices.
• API smoke/regression checks are easiest via JetBrains/REST Client files in api/ using shared vars in api/_variables.http.

Project-Specific Conventions

• Backend response contract is ApiResponse<T> (success, message, data, errors, timestamp) from backend/src/main/java/com/pesa/common/response/ApiResponse.java.
• Auth is JWT bearer everywhere; admin and user tokens are separate (admin_token in backoffice localStorage).
• RBAC is annotation-driven (@PreAuthorize) in admin endpoints; preserve role checks when adding admin APIs.
• Flutter state direction is Riverpod-first (mobile/AGENTS.md); do not extend mobile/legacy/ BLoC code for new features.
• Keep generated/build artifacts out of edits unless required (backend/target/, mobile/build/, mobile/ios/Pods/).

Integration Notes / Gotchas

• Apple Silicon: Kafka/Zookeeper are pinned to linux/amd64 in docker-compose.yml.
• Seed admin credentials are documented in api/admin.http (from V2__update_rates.sql); treat as dev-only.
• Repo currently has .env but no .env.example; use existing .env values as baseline.
• Kafka is provisioned in infra/config, but there are no active @KafkaListener/KafkaTemplate usages in current backend source.