KakeiBuddy Software Documentation

1. Introduction

KakeiBuddy is a mobile budgeting companion designed to help users track spending, form budgeting habits, complete financial missions, and receive AI-assisted coaching suggestions. The system includes a mobile app, backend API, local and server-side persistence, optional research workflows, and an AI policy component.

2. Purpose

The purpose of this document is to describe the software at a level suitable for developers, project evaluators, and stakeholders. It summarizes the system goals, users, functional requirements, non-functional requirements, architecture, modules, data handling, and deployment approach.

3. Scope

KakeiBuddy supports:

• Budget profile setup.
• Income and expense logging.
• Local spending summaries.
• Mission and challenge participation.
• Points and badge-style gamification.
• AI-assisted budgeting recommendations.
• Notifications and reminders.
• Optional privacy-aware research participation.
• Backend APIs for users, challenges, summaries, coach suggestions, and research data.

The system does not currently provide bank account integration, multi-user household budgets, or full financial planning automation.

4. Intended Users

Primary users:

• Individuals who want to track income, expenses, savings goals, and budgeting habits.

Secondary users:

• Developers maintaining the app and backend.
• Researchers or administrators reviewing anonymized study data.
• Project evaluators or panel members reviewing the software design.

5. Product Perspective

KakeiBuddy is a mobile-first application. It uses local SQLite for transaction-level user data and a FastAPI backend for shared challenge templates, accepted challenges, aggregate summaries, AI coaching, and optional research records.

6. Functional Requirements

6.1 Onboarding

• The system shall guide new users through introduction screens.
• The system shall collect budget profile details.
• The system shall allow users to configure privacy and data mode preferences.
• The system shall allow users to join or skip Research Mode.

6.2 Transaction Management

• The system shall allow users to create income and expense transactions.
• The system shall classify transactions by type and category.
• The system shall store transaction entries locally.
• The system shall support expense review through lists and visual summaries.

6.3 Budget Summaries

• The system shall compute weekly and monthly spending summaries.
• The system shall group expense totals by major category.
• The system shall use summaries for dashboard insights, coach input, and optional sync.

6.4 Challenges And Rewards

• The system shall display challenge templates.
• The system shall allow users to accept monthly missions.
• The system shall track mission progress.
• The system shall allow completed rewards to be claimed.
• The system shall show points and badges.

6.5 AI Coach

• The system shall accept normalized budget state values.
• The system shall return coaching suggestions.
• The system shall use a trained DDPG policy when available.
• The system shall use fallback rules if the policy cannot be used.
• The system shall identify whether fallback behavior was used.

6.6 Notifications

• The system shall support reminder and nudge settings.
• The system shall schedule supported local notifications.
• The system shall allow notification settings to be changed.

6.7 Research Mode

• The system shall support optional consent.
• The system shall support research track selection.
• The system shall collect survey, assessment, reflection, event, and progress data when enabled.
• The system shall protect research export with a token.
• The system shall avoid exporting raw transaction rows and notes as research data.

7. Non-Functional Requirements

Usability

The app should provide simple budgeting workflows with clear navigation through Home, Expenses, Challenge, Coach, and Profile tabs.

Privacy

Transaction-level data should remain local-first. Research export should use anonymous and aggregate data only unless future requirements explicitly change this boundary.

Reliability

The backend should use database startup checks and seed required reference data. The coach endpoint should continue returning suggestions even when the AI model is unavailable.

Maintainability

The codebase should keep API routes, services, models, and schemas separated. Mobile API behavior should stay centralized in utility modules.

Portability

The mobile app should run in Expo-supported environments. The backend should run locally, in Docker, and on Render.

8. System Architecture

KakeiBuddy uses three primary components:

• Mobile client: Expo React Native app with local SQLite.
• Backend API: FastAPI service with SQLAlchemy async models.
• AI policy: Stable Baselines3 DDPG model artifact with fallback rules.

User
  -> Expo Mobile App
  -> Local SQLite
  -> FastAPI Backend
  -> SQLite or PostgreSQL
  -> AI Coach Policy or Fallback Rules

9. Module Description

Mobile App Module

Responsible for user interface, local data entry, charts, onboarding, notifications, privacy settings, and API calls.

Backend API Module

Responsible for user records, challenge templates, accepted challenges, summaries, coach suggestions, research data, and admin access.

Database Module

Responsible for local SQLite tables on mobile and SQLAlchemy-managed tables on the backend.

AI Coach Module

Responsible for converting normalized budget state into suggested budget adjustments.

Research Module

Responsible for consent, instruments, responses, reflections, events, progress snapshots, and protected export.

10. Data Handling

KakeiBuddy separates transaction-level data from aggregate and research-safe data. Mobile SQLite stores raw transactions. Backend APIs receive selected records such as summaries, challenge metrics, consent, research responses, and anonymous events.

Private Mode limits synced metrics. Sync Mode permits selected aggregate sync behavior.

11. External Interfaces

Mobile interface:

• Expo app screens and native device capabilities such as local notifications and SQLite.

Backend interface:

• REST-style JSON endpoints through FastAPI.
• FastAdmin mounted at /admin.
• OpenAPI documentation at /docs.

Deployment interface:

• Docker Compose for local backend deployment.
• Render blueprint for hosted backend and PostgreSQL.

12. Deployment

The backend can run locally through Python, through Docker Compose, or through Render. Render configuration is stored in render.yaml and includes a web service plus PostgreSQL database.

The mobile app runs through Expo during development. Production mobile builds should configure EXPO_PUBLIC_API_URL to the deployed backend.

13. Risks And Constraints

• AI model dependencies may be heavier than basic backend dependencies.
• Mobile network routing differs between physical devices, simulators, emulators, and web.
• Research features require careful privacy review when changed.
• Production browser origins must be configured as the backend CORS allowlist before public browser clients are used.

14. Future Improvements

• Add automated backend route tests.
• Add mobile component or flow tests.
• Add screenshots to user documentation.
• Add API examples generated from Pydantic schemas.
• Add migration tooling for larger database changes.
• Add CI checks for linting and tests.

Back to Documentation Home