# bima2-creator/easy-expense architecture

> Architecture diagram of the GitHub repository bima2-creator/easy-expense, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bima2-creator/easy-expense
- Repository: https://github.com/bima2-creator/easy-expense

## Overview

Easy Expense is a project-expense tracker: users capture or enter a receipt, review its extracted details, and save an expense; they can then organize expenses by project and work order, review summaries, and export reports. The frontend is an Expo Router app backed by FastAPI, MongoDB, OCR.space, and local receipt-file storage. The source excerpts are partial, so some screen-to-API actions and backend subsystem details are represented only where the README or sampled code supports them.

Main entry points: [`frontend/src/api.ts`](https://github.com/bima2-creator/easy-expense/blob/main/frontend/src/api.ts) (API client), [`frontend/src/components/ExpenseForm.tsx`](https://github.com/bima2-creator/easy-expense/blob/main/frontend/src/components/ExpenseForm.tsx) (Expense form), [`frontend/app/scan.tsx`](https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/scan.tsx) (Receipt scanning), [`backend/server.py`](https://github.com/bima2-creator/easy-expense/blob/main/backend/server.py) (FastAPI service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Receipt capture"]
  node_scan["Receipt scanning<br/>[scan.tsx]"]
end

subgraph group_expenses["Expense management"]
  node_manual["Manual expense entry<br/>[add.tsx]"]
  node_expense_detail["Expense details<br/>[&#91;id&#93;.tsx]"]
  node_expense_list["Expense list<br/>[expenses.tsx]"]
  node_expense_form["Expense form<br/>[ExpenseForm.tsx]"]
  node_categories["Category management<br/>[categories.tsx]"]
  node_category_state["Category state<br/>[categories.tsx]"]
  node_settings["Settings<br/>[settings.tsx]"]
end

subgraph group_projects["Projects and work orders"]
  node_projects_list["Project list<br/>[projects.tsx]"]
  node_project_detail["Project details<br/>[&#91;id&#93;.tsx]"]
  node_workorder_detail["Work order details<br/>[&#91;id&#93;.tsx]"]
end

subgraph group_insights["Summaries and reports"]
  node_home["Home dashboard<br/>[index.tsx]"]
  node_reports["Reports screen<br/>[reports.tsx]"]
end

subgraph group_backend["Backend services"]
  node_api_client["API client<br/>[api.ts]"]
  node_api_server["FastAPI service<br/>[server.py]"]
  node_ocr["OCR.space"]
  node_mongo[("MongoDB")]
  node_receipt_files[("Receipt file storage")]
end

node_user(("User"))

node_user -->|"captures receipt"| node_scan
node_user -->|"enters expense"| node_manual
node_user -->|"views activity"| node_home
node_scan -->|"submits scan"| node_api_client
node_scan -->|"edits details"| node_expense_form
node_manual -->|"collects details"| node_expense_form
node_expense_detail -->|"edits expense"| node_expense_form
node_expense_form -->|"saves expense"| node_api_client
node_expense_list -->|"loads expenses"| node_api_client
node_expense_detail -->|"loads and updates"| node_api_client
node_home -->|"loads summary"| node_api_client
node_projects_list -->|"loads projects"| node_api_client
node_project_detail -->|"manages project"| node_api_client
node_project_detail -->|"opens work order"| node_workorder_detail
node_workorder_detail -->|"manages work order"| node_api_client
node_reports -->|"requests reports"| node_api_client
node_categories -->|"manages categories"| node_category_state
node_scan -->|"uses categories"| node_category_state
node_expense_form -->|"uses categories"| node_category_state
node_settings -.->|"configures service"| node_api_client
node_api_client -->|"calls API"| node_api_server
node_api_server -->|"requests text extraction"| node_ocr
node_api_server -->|"reads and writes"| node_mongo
node_api_server -->|"stores receipt files"| node_receipt_files

click node_home "https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/(tabs)/index.tsx"
click node_scan "https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/scan.tsx"
click node_manual "https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/add.tsx"
click node_expense_detail "https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/expense/%5Bid%5D.tsx"
click node_expense_list "https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/(tabs)/expenses.tsx"
click node_expense_form "https://github.com/bima2-creator/easy-expense/blob/main/frontend/src/components/ExpenseForm.tsx"
click node_categories "https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/categories.tsx"
click node_category_state "https://github.com/bima2-creator/easy-expense/blob/main/frontend/src/categories.tsx"
click node_projects_list "https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/(tabs)/projects.tsx"
click node_project_detail "https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/project/%5Bid%5D.tsx"
click node_workorder_detail "https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/workorder/%5Bid%5D.tsx"
click node_reports "https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/(tabs)/reports.tsx"
click node_settings "https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/settings.tsx"
click node_api_client "https://github.com/bima2-creator/easy-expense/blob/main/frontend/src/api.ts"
click node_api_server "https://github.com/bima2-creator/easy-expense/blob/main/backend/server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scan,node_user toneBlue
class node_manual,node_expense_detail,node_expense_list,node_expense_form,node_categories,node_category_state,node_settings toneAmber
class node_projects_list,node_project_detail,node_workorder_detail toneMint
class node_home,node_reports toneRose
class node_api_client,node_api_server,node_ocr,node_mongo,node_receipt_files toneIndigo
```

## Components

### Receipt capture

- [Receipt scanning](https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/scan.tsx): `frontend/app/scan.tsx`

### Expense management

- [Manual expense entry](https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/add.tsx): `frontend/app/add.tsx`
- [Expense details](https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/expense/%5Bid%5D.tsx): `frontend/app/expense/[id].tsx`
- [Expense list](https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/(tabs)/expenses.tsx): `frontend/app/(tabs)/expenses.tsx`
- [Expense form](https://github.com/bima2-creator/easy-expense/blob/main/frontend/src/components/ExpenseForm.tsx): `frontend/src/components/ExpenseForm.tsx`
- [Category management](https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/categories.tsx): `frontend/app/categories.tsx`
- [Category state](https://github.com/bima2-creator/easy-expense/blob/main/frontend/src/categories.tsx): `frontend/src/categories.tsx`
- [Settings](https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/settings.tsx): `frontend/app/settings.tsx`

### Projects and work orders

- [Project list](https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/(tabs)/projects.tsx): `frontend/app/(tabs)/projects.tsx`
- [Project details](https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/project/%5Bid%5D.tsx): `frontend/app/project/[id].tsx`
- [Work order details](https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/workorder/%5Bid%5D.tsx): `frontend/app/workorder/[id].tsx`

### Summaries and reports

- [Home dashboard](https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/(tabs)/index.tsx): `frontend/app/(tabs)/index.tsx`
- [Reports screen](https://github.com/bima2-creator/easy-expense/blob/main/frontend/app/(tabs)/reports.tsx): `frontend/app/(tabs)/reports.tsx`

### Backend services

- [API client](https://github.com/bima2-creator/easy-expense/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [FastAPI service](https://github.com/bima2-creator/easy-expense/blob/main/backend/server.py): `backend/server.py`
- **OCR.space**
- **MongoDB**
- **Receipt file storage**

### Other components

- **User**

## Connections

- User → Receipt scanning: captures receipt
- User → Manual expense entry: enters expense
- User → Home dashboard: views activity
- Receipt scanning → API client: submits scan
- Receipt scanning → Expense form: edits details
- Manual expense entry → Expense form: collects details
- Expense details → Expense form: edits expense
- Expense form → API client: saves expense
- Expense list → API client: loads expenses
- Expense details → API client: loads and updates
- Home dashboard → API client: loads summary
- Project list → API client: loads projects
- Project details → API client: manages project
- Project details → Work order details: opens work order
- Work order details → API client: manages work order
- Reports screen → API client: requests reports
- Category management → Category state: manages categories
- Receipt scanning → Category state: uses categories
- Expense form → Category state: uses categories
- Settings → API client: configures service
- API client → FastAPI service: calls API
- FastAPI service → OCR.space: requests text extraction
- FastAPI service → MongoDB: reads and writes
- FastAPI service → Receipt file storage: stores receipt files