KakeiBuddy Architecture

KakeiBuddy is split into a mobile client, backend API, and AI policy artifact.

Expo Mobile App
  | local SQLite
  | apiFetch()
  v
FastAPI Backend
  | SQLAlchemy async
  v
SQLite or PostgreSQL

Coach endpoint
  | loads policy
  v
DDPG model or fallback rules

Mobile App

The mobile app is an Expo Router application. Main user-facing areas are:

• Home dashboard: current progress, summaries, reminders, and research checkpoint prompts.
• Expenses: charts and transaction views.
• Challenge: mission dashboard and completed mission rewards.
• Coach: AI-assisted suggestions and reflection flow.
• Profile: budget profile, achievements, settings, privacy, notifications, and research controls.

Backend API

The backend is a FastAPI app in backend/main.py. It mounts FastAdmin at /admin, enables local CORS origins for Expo development, and registers user, challenge, coach, and research routes.

Startup performs database setup and seed behavior through the app lifespan handler.

Persistence

Mobile SQLite

Mobile SQLite is the primary store for transaction-level user data. It supports offline use and local reports.

Key local data:

• Transactions.
• Categories.
• Weekly and monthly summaries.
• Local points, badges, and streak state.
• Repeat entries.

Backend Database

The backend uses DATABASE_URL first, PostgreSQL environment variables second, and local SQLite as a fallback.

Backend data includes:

• Anonymous users.
• Budget profile records.
• Challenge templates and accepted user challenges.
• Weekly and monthly summary records.
• Badges.
• Research consent, responses, events, metrics, reflections, and progress snapshots.

API Communication

The mobile app uses mobile/utils/api.js for backend requests. It normalizes configured and fallback base URLs, then tries each URL with a request timeout.

Fallback base URL order:

1. EXPO_PUBLIC_API_URL, if configured.
2. Expo development host on port 8000.
3. Android emulator alias http://10.0.2.2:8000 on Android.
4. http://localhost:8000.

AI Coach

The coach endpoint accepts normalized budget ratios and previous action values. It tries to load backend/ai/ddpg_budget_policy.zip through BudgetPolicy.

If policy loading or prediction fails, the endpoint uses fallback rules. The response includes:

• policy_version
• state_contract_version
• fallback_used
• suggestions

This makes AI behavior transparent enough for UI display and debugging.

Research And Privacy

Research Mode is optional. The app stores research state locally and syncs selected records to the backend after consent.

Important privacy boundaries:

• Exact transaction rows and notes are local-first.
• Private Mode blocks sensitive metric keys from sync.
• Research export requires RESEARCH_EXPORT_TOKEN.
• Research export is designed around anonymous study metrics, not raw personal finance records.

Deployment Architecture

Local Docker uses the root compose.yaml and root Dockerfile. Render uses render.yaml with rootDir: backend, installs backend/requirements.txt, and starts uvicorn main:app.

For production-like deployments, PostgreSQL is preferred over backend local SQLite.

Back to Documentation Home