micro-plan.md

Micro-Level API Specification for Expense Tracker

1. Authentication Service

Detailed Design: Auth Service API

Method	Path	Description	Request Body	Response Body
POST	/auth/signup/email	Register a new user with email+password	{ email, password, name? }	{ access_token, refresh_token, user }
POST	/auth/login/email	Login with email+password	{ email, password }	{ access_token, refresh_token, user }
POST	/auth/login/google	Login / signup via Google OAuth token	{ id_token }	{ access_token, refresh_token, user }
POST	/auth/refresh	Refresh JWT when access token expires	{ refresh_token }	{ access_token, refresh_token }
POST	/auth/password/reset/request	Send password-reset email link	{ email }	{ success: true }
POST	/auth/password/reset/confirm	Set new password via reset token	{ reset_token, new_password }	{ success: true }
POST	/auth/token/verify	Verify access token and auto-login	{ access_token }	{ user }

All “auth” endpoints return standard HTTP 4xx on error and 200 + JSON on success.

---

2. User Service

Detailed Design: User Service API

Method	Path	Description	Request Body	Response Body
GET	/users/me	Get current user profile	–	{ id, name, email, image_url, currency, created_at }
PATCH	/users/me	Update profile & preferences	{ name?, image_url?, currency? }	{ id, name, email, image_url, currency, created_at }
DELETE	/users/me	Delete own account	–	{ success: true, message: "User account scheduled for deletion." }

All user endpoints require a valid Authorization: Bearer … header.

---

3. Group Service

Detailed Design: Group Service API

Method	Path	Description	Request Body	Response Body
POST	/groups	Create a new group	{ name, currency?, image_url? }	{ group }
GET	/groups	List all groups current user belongs to	–	{ groups: [ … ] }
GET	/groups/{group_id}	Get one group’s details	–	{ group, members: […], settings: {…} }
PATCH	/groups/{group_id}	Update group metadata	{ name?, currency?, image_url? }	{ group }
DELETE	/groups/{group_id}	Delete a group	–	{ success: true }
POST	/groups/join	Join group via invite token	{ joinCode }	{ group, members }
POST	/groups/{group_id}/leave	Leave the group	–	{ success: true }
GET	/groups/{group_id}/members	List members & roles	–	{ members: [ { user_id, role, joined_at } ] }
PATCH	/groups/{group_id}/members/{member_id}	Change a member’s role (admin/member)	{ role }	{ member }
DELETE	/groups/{group_id}/members/{member_id}	Kick or remove a member	–	{ success: true }

All group endpoints require Bearer auth and membership (role checks on PATCH/DELETE).

---

4. Expense Management Service

Detailed Design: Expense Service API

Method	Path	Description	Request Body	Response Body
POST	/groups/{group_id}/expenses	Create new expense	{ description, receiptUrls? }	{ expense }
GET	/groups/{group_id}/expenses	List group expenses (paginated, filterable)	–	{ expenses: […], pagination: {…} }
GET	/groups/{group_id}/expenses/{expense_id}	Get one expense (details, settlements)	–	{ expense, relatedSettlements: […] }
PATCH	/groups/{group_id}/expenses/{expense_id}	Update expense	{ description?, receiptUrls? }	{ expense }
DELETE	/groups/{group_id}/expenses/{expense_id}	Delete expense	–	{ success: true }
POST	/groups/{group_id}/expenses/{expense_id}/attachments	Upload attachment for an expense	File (form-data)	{ attachment_key, url }
GET	/groups/{group_id}/expenses/{expense_id}/attachments/{key}	Get/download an attachment	–	File stream

All expense endpoints require Bearer auth and group membership.

---

5. Settlement Service

Detailed Design: Expense Service API (Settlement Management)

Method	Path	Description	Request Body	Response Body
POST	/groups/{group_id}/settlements	Manually record a payment settlement	{ payer_id, payee_id, amount, paidAt?, desc? }	{ settlement }
GET	/groups/{group_id}/settlements	List group settlements (paginated, filterable)	–	{ settlements: […], pagination: {…} }
GET	/groups/{group_id}/settlements/{settlement_id}	Get one settlement	–	{ settlement }
PATCH	/groups/{group_id}/settlements/{settlement_id}	Update settlement (e.g., mark as paid)	{ status, paidAt? }	{ settlement }
DELETE	/groups/{group_id}/settlements/{settlement_id}	Delete/undo a settlement	–	{ success: true }
POST	/groups/{group_id}/settlements/optimize	Calculate optimized (simplified) settlements	–	{ optimizedSettlements: […] }

All settlement endpoints require Bearer auth and group membership.

---

6. Friends Balance Aggregation Service

Detailed Design: Expense Service API (Friends Balance Section)

Method	Path	Description	Request Body	Response Body
GET	/users/me/friends-balance	Get current user’s aggregated balances with friends	–	{ friendsBalance: [{ friend_id, name, balance, currency }] }
GET	/users/me/balance-summary	Get current user’s overall financial summary	–	{ totalOwedToYou, totalYouOwe, netBalance, currency, groupsSummary: [{}] }
GET	/groups/{group_id}/users/{user_id}/balance	Get a user’s balance in a specific group	–	{ userBalance: {…} }

All balance endpoints require Bearer auth.

---

7. Enhanced Analytics Service

Detailed Design: Expense Service API (Analytics Section)

Method	Path	Description	Request Body	Response Body
GET	/groups/{group_id}/analytics	Group expense analytics & trends	Query: ?period&year&month	{ analytics: {…}, expenseTrends: […], memberContributions: […] }
GET	/users/me/analytics	Personal expense analytics	Query: ?period&year&month	{ personalStats: {…}, groupBreakdown: […] }
GET	/groups/{group_id}/analytics/summary	Total spent per user, per-category	?from&to	{ per_user: […], per_category: […] }
GET	/groups/{group_id}/analytics/trends	Time-series of balances & spendings	?interval=daily/weekly	{ timeline: […dates & values] }

---

8. Real-Time Updates (WebSockets)

• WS /ws/groups/{group_id} Push real-time events: new expense, group member change, settlement, etc.

---

Notes & Next Steps

• Auth middleware on every non-public route to decode JWT and load current_user. (Auth Service)
• Role checks (group admin vs. member) enforced in Group & Expense PATCH/DELETE. (Group Service, Expense Service)
• Payload schemas defined via Pydantic for request validation & auto-docs.
• File uploads: use multipart/form-data + S3- or GridFS-backed storage.
• Rate-limit expensive ops (graph simplification) or offload to background worker (e.g. Celery/RQ). (Expense Service)
• Settlement Algorithm: Implement directed graph optimization for debt minimization (Expense Service)
• Friends Balance: Cross-group aggregation with real-time balance updates (Expense Service)
• Database Schema: All services interact with the Non-Relational Database Schema.