KakeiBuddy Developer Guide

This guide is for developers setting up, debugging, or extending KakeiBuddy.

Prerequisites

Node.js and npm.
Expo CLI through npx expo.
Python 3.12 recommended.
Docker Desktop or compatible Docker runtime, optional.
Android Studio or Xcode if running native builds.

Backend Setup

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload

The backend starts at http://localhost:8000.

Useful URLs:

http://localhost:8000/ - health/root response.
http://localhost:8000/docs - FastAPI Swagger UI.
http://localhost:8000/admin - FastAdmin interface.

On startup, the backend:

Creates missing database tables.
Runs lightweight schema column checks.
Seeds the default admin user.
Seeds income ranges.
Seeds default badges.
Seeds challenge templates from 004_seed_challenge_templates_50 (1).sql when available.

AI Coach Dependencies

backend/requirements.txt is enough to run the API with fallback coach suggestions. To use the trained DDPG policy instead of fallback rules, install the AI dependency set:

cd backend
pip install -r requirements-ai.txt

The trained policy file is expected at:

backend/ai/ddpg_budget_policy.zip

If the model or AI dependencies are unavailable, /coach/suggestions still returns suggestions with fallback_used: true.

Mobile Setup

cd mobile
npm install
npm start

Available scripts:

Command	Purpose
`npm start`	Starts Expo development server
`npm run android`	Runs Android native app
`npm run ios`	Runs iOS native app
`npm run web`	Starts Expo web
`npm run lint`	Runs Expo lint
`npm run reset-project`	Expo starter reset script, avoid unless intentionally resetting app structure

Environment Variables

Backend

The backend loads .env.local from the backend/ working directory.

Variable	Purpose	Default
`DATABASE_URL`	Full database URL. Render Postgres URLs are normalized to asyncpg.	Local SQLite
`DB_HOST`	PostgreSQL host when not using `DATABASE_URL`.	None
`DB_USER`	PostgreSQL user.	`postgres`
`DB_PASSWORD`	PostgreSQL password.	None
`DB_PASSWORD_FILE`	File containing PostgreSQL password.	None
`DB_NAME`	PostgreSQL database name.	`kakeibuddy`
`DB_PORT`	PostgreSQL port.	`5432`
`ADMIN_SECRET_KEY`	FastAdmin secret key.	`gwapoak` in local code default
`ADMIN_PASSWORD`	Seeded admin password for user `admin`.	`changeme`
`RESEARCH_EXPORT_TOKEN`	Required header token for admin research export.	None

Mobile

Variable	Purpose
`EXPO_PUBLIC_API_URL`	Preferred backend base URL, for example `http://localhost:8000`
`EXPO_PUBLIC_RESEARCH_TRACK`	Default research track, usually `tale` or `gala`

If EXPO_PUBLIC_API_URL is not set, mobile/utils/api.js tries Expo host discovery, Android emulator 10.0.2.2, and localhost.

Local Data Model

The mobile app uses Expo SQLite database kakeibuddy.db. Important local tables include:

transactions
category
weekly_summary
monthly_summary
points_streaks
badges
badges_earned
repeat_entry
income_range

Local category seed data is inserted during initDB.

Backend Structure

Path	Responsibility
`backend/main.py`	FastAPI app, startup seeding, middleware, route registration
`backend/routes/`	HTTP endpoints
`backend/services/`	Business logic
`backend/models/`	SQLAlchemy models
`backend/schemas/`	Pydantic request and response schemas
`backend/db/`	Database connection and schema migration helpers
`backend/ai/`	AI policy inference wrapper and model artifact
`backend/admin/`	FastAdmin model registration

Mobile Structure

Path	Responsibility
`mobile/app/`	Expo Router screens and layouts
`mobile/app/(tabs)/`	Main app tabs
`mobile/components/`	Reusable UI components
`mobile/utils/`	API, notifications, local storage, research, game, and budget helpers
`mobile/utils/database/`	SQLite create, select, sync, and destroy helpers
`mobile/assets/`	App icons and images
`mobile/constants/`	Shared styling constants

Data Flow

Users create local budget data in the mobile app.
Mobile SQLite stores transactions and summaries on device.
Local utilities compute monthly metrics, challenge metrics, and dashboard values.
When Sync Mode or research flows require backend communication, the app calls FastAPI through apiFetch.
Backend persists aggregate summaries, challenge progress, consent, research responses, and events.
Coach suggestions are requested from /coach/suggestions.

Common Development Workflows

Run backend and mobile together:

cd backend
uvicorn main:app --reload

In another terminal:

cd mobile
npm start

Run mobile lint:

cd mobile
npm run lint

Run the model smoke test:

cd model
pip install -r requirements.txt
python test_infer.py

The standalone model/requirements.txt may install heavier ML packages. For normal backend development, prefer backend/requirements-ai.txt.

Coding Notes

Keep API contracts in backend/schemas/ aligned with route behavior.
Prefer adding business logic to backend/services/, not route handlers.
Keep mobile API calls behind mobile/utils/api.js or domain-specific utilities.
Preserve Private Mode behavior when adding sync features.
Raw transaction rows and notes should not be added to research export without an explicit privacy review.

Back to Documentation Home