#15: Backend KPI & Time-Series APIs

Summary
We need an experienced AWS/backend developer to deliver pre-aggregated user KPIs, time-series endpoints for charting, and upcoming payment endpoints. The goal: provide small, fast endpoints the frontend can call (single request per dashboard load) and ensure data correctness, caching and tests.

Scope of work
Build (or finalize) the following endpoints (or confirm/extend existing):

1. GET /user/{user_id}/kpis
Returns: portfolio_value, total_appreciation, monthly_earning, monthly_payout, last_updated
Pre-aggregated for fast reads

2. GET /user/{user_id}/upcoming-payments?days=30
Returns scheduled installments due in the next X days (property, amount, due_date)

3. GET /market/history/{area_key}?days={n}
Returns time-series: [{date, price_per_sqm, valuation}] for charting

(Optional) GET /user/{id}/portfolio-snapshot/latest — aggregated per-property snapshot

Data sources & responsibilities:
- Use DynamoDB table (PropertyValuations) for historical price/sqm series.
- Use Monthly Snapshot Engine (Lambda) for latest snapshot/purchase_price/current_value.
- Map OCR outputs (SPA) to PaymentSchedule table to compute upcoming payments.

Ensure:
-Composite key time-series queries on DynamoDB are efficient and paginated
-Caching layer or TTL to prevent too many DLD API calls (redis or in-Lambda cache)
-Proper authentication and secure handling of API keys
-Unit tests and integration tests
-Swagger/OpenAPI doc for endpoints and example responses
-Provide a brief data model summary and documentation for frontend mapping.

Deliverables
- Implemented endpoints deployed to the existing AWS account (or provided as serverless Lambda + API Gateway definitions)
- Postman collection / OpenAPI spec
- Tests and instructions to run them
- Short runbook describing cron/timing of snapshot ingestion and where the KPIs derive from

Acceptance criteria
- /user/{user_id}/kpis returns accurate numbers for sample user (manual cross-check)
- /market/history/{area_key} returns at least the last 90 days or the available historical records (non-empty)
- /user/{id}/upcoming-payments lists the correct installments for sample user
- All endpoints respond within acceptable latency (<500ms median for KPI endpoint)
- Clear docs and a test user API key provided

Skills required
- AWS Lambda, API Gateway
- DynamoDB experience and time-series design (partition/sort keys)
- Node.js / Python (whichever current stack is in repo)
- Experience with serverless deployments and OpenAPI
- Familiarity with financial/real-estate data aggregation a plus