# kaushikp020603/myarthiq architecture

> Architecture diagram of the GitHub repository kaushikp020603/myarthiq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kaushikp020603/myarthiq
- Repository: https://github.com/kaushikp020603/myarthiq

## Overview

1. **Overall shape**
   - This is a **modular monolith** for personal/family/business finance.
   - The system is split into a **React/Vite frontend** and a **FastAPI backend**, with a shared domain broken into feature modules rather than separate services.

2. **Frontend presentation shell**
   - The frontend lives under `frontend/` and is a **single-page app** built with **React + TypeScript + Vite + Tailwind**.
   - `src/main.tsx` bootstraps the app, and `src/App.tsx` plus `src/components/layout/Shell.tsx` define the top-level chrome/navigation and feature routing experience.

3. **Feature-oriented UI structure**
   - UI code is organized by business capability under `src/features/` rather than by technical layer.
   - Major user-facing areas include **auth, dashboard, budgets, accounts, transactions, assets, goals, insurance, portfolio, reports, planning, sharing, security, admin, tools, and tutorials**.
   - This makes the frontend diagram best represented as a shell with many feature panels, each owning its own page and local components.

4. **Frontend data and state flow**
   - Shared client utilities live in `src/lib/`, including the API wrapper layer, query client, profile context, and finance-specific helper data.
   - Global UI/account state is handled in `src/store/` for **auth, profile, and theme**.
   - Most feature pages appear to call backend endpoints through feature-local `api.ts` files, with shared request/query infrastructure underneath.

5. **Backend application boundary**
   - The backend is a **FastAPI app** rooted at `backend/app/main.py`.
   - API routing is composed in `backend/app/api/v1/`, with module routers wired into a versioned API surface.
   - From an architecture diagram perspective, the backend is the central domain/API boundary between the frontend and persistence.

6. **Backend modular domains**
   - Business logic is split into `backend/app/modules/*`, including **auth, admin, accounts, budgets, dashboard, finance, goals, household, insurance, public, and wealth**.
   - Each module typically contains its own **models, schemas, services, and/or router**, showing a layered vertical-slice structure inside the monolith.
   - The frontend feature names map closely to these backend modules, which is the main functional correspondence in the system.

7. **Security and access control**
   - Authentication is JWT-based, with security support in `backend/app/core/security.py`.
   - RBAC is a first-class boundary in `backend/app/core/rbac.py`, and admin-specific data flows exist under `backend/app/modules/admin`.
   - This means the architecture should show **authenticated user flows** and **admin-only flows** as separate access paths through the same API.

8. **Persistence layer**
   - SQLAlchemy models are used for persistence, with database session management in `backend/app/db/session.py`.
   - The project is **SQLite-friendly for local development** but explicitly designed to be **PostgreSQL-ready**.
   - Alembic migrations in `backend/alembic/versions/` define the evolving schema, including families, joint accounts/transfers, goals metadata, budgets, and admin-related tables.

9. **Runtime support and background work**
   - There is a Celery worker setup in `backend/app/workers/`, indicating asynchronous/background processing.
   - Notification-related background jobs are present, and email support exists in `backend/app/core/email.py`.
   - This adds a second execution path besides the request/response API: **scheduled or async tasks** for notifications and similar jobs.

10. **Initialization and operational scripts**
   - `backend/database/` contains bootstrap and migration helpers such as `create_admin.py`, `seed.py`, and schema conversion utilities.
   - These scripts support first-run setup and data migration rather than end-user features.
   - For architecture, they are best shown as operational tooling attached to the backend/data layer.

11. **Domain cross-cuts**
   - Shared finance helpers live in backend core/modules and frontend `src/lib/` rather than inside a single feature.
   - The app includes shared concepts like **families, profiles, banks, expense categories, and net worth/wealth calculations**, which cut across several user flows.
   - These are important conceptual boundaries when drawing the domain model, because many screens depend on the same household/profile context.

12. **Public vs authenticated surfaces**
   - The frontend includes landing, legal, login/signup/password-change, and other onboarding pages alongside the authenticated product shell.
   - The backend has a `public` module, suggesting some endpoints are intentionally available without login.
   - So the system has a clear split between **public marketing/onboarding**, **authenticated finance workspace**, and **admin console**.

13. **Testing and documentation**
   - Backend tests cover smoke, family behavior, and budgets/privacy concerns.
   - The `docs/` folder contains architecture and product breakdown documentation, which likely aligns with the intended module boundaries.
   - These are supporting artifacts, but they confirm that the main architectural concerns are privacy, multi-family context, and feature modularity.

14. **Key diagram takeaway**
   - The best architecture diagram is: **React SPA shell → feature pages/hooks/api clients → FastAPI versioned routers → module services/models → SQLAlchemy/PostgreSQL/SQLite**, with **JWT/RBAC** guarding access and **Celery/email** handling asynchronous side effects.

Main entry points: [`frontend/src/features/dashboard/DashboardPage.tsx`](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/dashboard/DashboardPage.tsx) (Workspace), [`frontend/src/App.tsx`](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/App.tsx) (App), [`backend/app/modules/__init__.py`](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/modules/__init__.py) (Modules), [`backend/app/api/v1/router.py`](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/api/v1/router.py) (V1 Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_main["Main<br/>SPA bootstrap<br/>[main.tsx]"]
  node_frontend_app["App<br/>route shell<br/>[App.tsx]"]
  node_frontend_shell["Shell<br/>layout chrome<br/>[Shell.tsx]"]
  node_frontend_auth["Auth UI<br/>auth feature<br/>[AuthPage.tsx]"]
  node_frontend_workspace["Workspace<br/>feature hub<br/>[DashboardPage.tsx]"]
  node_frontend_budgets["Budgets<br/>budget feature<br/>[BudgetsPage.tsx]"]
  node_frontend_accounts["Accounts<br/>[AccountsPage.tsx]"]
  node_frontend_transactions["Transactions<br/>transaction feature"]
  node_frontend_goals["Goals<br/>goal feature<br/>[GoalsPage.tsx]"]
  node_frontend_insurance["Insurance<br/>[InsurancePage.tsx]"]
  node_frontend_portfolio["Portfolio<br/>wealth feature<br/>[PortfolioPage.tsx]"]
  node_frontend_reports["Reports<br/>analytics feature<br/>[ReportsPage.tsx]"]
  node_frontend_tools["Tools<br/>settings feature<br/>[SettingsPage.tsx]"]
  node_frontend_admin["Admin UI<br/>admin console<br/>[AdminPage.tsx]"]
  node_frontend_shared["Shared Lib<br/>client infra<br/>[api.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_main["API App<br/>[main.py]"]
  node_backend_router["V1 Router<br/>api composition<br/>[router.py]"]
  node_backend_core["Core<br/>security & config<br/>[security.py]"]
  node_backend_domains["Modules<br/>domain slices<br/>[__init__.py]"]
  node_backend_persistence[("Persistence<br/>ORM & session<br/>[session.py]")]
  node_backend_migrations["Migrations<br/>schema history"]
end

subgraph group_runtime["Runtime & Ops"]
  node_backend_workers["Workers<br/>async jobs<br/>[celery_app.py]"]
  node_backend_bootstrap["DB Tools<br/>bootstrap scripts<br/>[create_admin.py]"]
end

node_frontend_main -->|"boots"| node_frontend_app
node_frontend_app -->|"uses"| node_frontend_shell
node_frontend_app -->|"routes"| node_frontend_auth
node_frontend_app -->|"routes"| node_frontend_workspace
node_frontend_workspace -->|"includes"| node_frontend_budgets
node_frontend_workspace -->|"includes"| node_frontend_accounts
node_frontend_workspace -->|"includes"| node_frontend_transactions
node_frontend_workspace -->|"includes"| node_frontend_goals
node_frontend_workspace -->|"includes"| node_frontend_insurance
node_frontend_workspace -->|"includes"| node_frontend_portfolio
node_frontend_workspace -->|"includes"| node_frontend_reports
node_frontend_workspace -->|"includes"| node_frontend_tools
node_frontend_workspace -->|"includes"| node_frontend_admin
node_frontend_workspace -->|"depends on"| node_frontend_shared
node_frontend_shared -->|"calls"| node_backend_router
node_frontend_auth -->|"calls"| node_backend_router
node_backend_main -->|"mounts"| node_backend_router
node_backend_router -->|"dispatches to"| node_backend_domains
node_backend_domains -->|"guards with"| node_backend_core
node_backend_domains -->|"persists via"| node_backend_persistence
node_backend_persistence -->|"evolves with"| node_backend_migrations
node_backend_domains -.->|"enqueues"| node_backend_workers
node_backend_bootstrap -.->|"initializes"| node_backend_persistence
node_backend_core -.->|"supports"| node_backend_workers

click node_frontend_main "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/main.tsx"
click node_frontend_app "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/App.tsx"
click node_frontend_shell "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/components/layout/Shell.tsx"
click node_frontend_auth "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/auth/AuthPage.tsx"
click node_frontend_workspace "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/dashboard/DashboardPage.tsx"
click node_frontend_budgets "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/budgets/BudgetsPage.tsx"
click node_frontend_accounts "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/accounts/AccountsPage.tsx"
click node_frontend_transactions "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/transactions/TransactionsPage.tsx"
click node_frontend_goals "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/goals/GoalsPage.tsx"
click node_frontend_insurance "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/insurance/InsurancePage.tsx"
click node_frontend_portfolio "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/portfolio/PortfolioPage.tsx"
click node_frontend_reports "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/reports/ReportsPage.tsx"
click node_frontend_tools "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/tools/SettingsPage.tsx"
click node_frontend_admin "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/admin/AdminPage.tsx"
click node_frontend_shared "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/lib/api.ts"
click node_backend_main "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/main.py"
click node_backend_router "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/api/v1/router.py"
click node_backend_core "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/core/security.py"
click node_backend_domains "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/modules/__init__.py"
click node_backend_persistence "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/db/session.py"
click node_backend_migrations "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/alembic/versions/0001_initial_schema.py"
click node_backend_workers "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/workers/celery_app.py"
click node_backend_bootstrap "https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/database/create_admin.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_frontend_main,node_frontend_app,node_frontend_shell,node_frontend_auth,node_frontend_workspace,node_frontend_budgets,node_frontend_accounts,node_frontend_transactions,node_frontend_goals,node_frontend_insurance,node_frontend_portfolio,node_frontend_reports,node_frontend_tools,node_frontend_admin,node_frontend_shared toneBlue
class node_backend_main,node_backend_router,node_backend_core,node_backend_domains,node_backend_persistence,node_backend_migrations toneAmber
class node_backend_workers,node_backend_bootstrap toneMint
```

## Components

### Frontend

React/Vite single-page app and feature modules

- [Main](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/main.tsx): SPA bootstrap · Mounts the React app and initializes client runtime. · `frontend/src/main.tsx`
- [App](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/App.tsx): route shell · Top-level application routing and product mode switching. · `frontend/src/App.tsx`
- [Shell](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/components/layout/Shell.tsx): layout chrome · Authenticated workspace chrome, navigation, and feature framing. · `frontend/src/components/layout/Shell.tsx`
- [Auth UI](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/auth/AuthPage.tsx): auth feature · Login, signup, password reset, and auth-specific presentation. · `frontend/src/features/auth/AuthPage.tsx`
- [Workspace](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/dashboard/DashboardPage.tsx): feature hub · Core authenticated finance workspace composed of major feature pages. · `frontend/src/features/dashboard/DashboardPage.tsx`
- [Budgets](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/budgets/BudgetsPage.tsx): budget feature · Budget grid, insights, reports, and daily logging. · `frontend/src/features/budgets/BudgetsPage.tsx`
- [Accounts](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/accounts/AccountsPage.tsx): accounts feature · Account management and transfer workflows. · `frontend/src/features/accounts/AccountsPage.tsx`
- [Transactions](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/transactions/TransactionsPage.tsx): transaction feature · Transaction review and operational transaction workflows. · `frontend/src/features/transactions/TransactionsPage.tsx`
- [Goals](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/goals/GoalsPage.tsx): goal feature · Goal planning, cards, and goal drawer workflows. · `frontend/src/features/goals/GoalsPage.tsx`
- [Insurance](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/insurance/InsurancePage.tsx): insurance feature · Insurance records and detail drawer flows. · `frontend/src/features/insurance/InsurancePage.tsx`
- [Portfolio](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/portfolio/PortfolioPage.tsx): wealth feature · Portfolio and wealth-oriented views. · `frontend/src/features/portfolio/PortfolioPage.tsx`
- [Reports](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/reports/ReportsPage.tsx): analytics feature · Reporting and financial summaries. · `frontend/src/features/reports/ReportsPage.tsx`
- [Tools](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/tools/SettingsPage.tsx): settings feature · Import, install, settings, onboarding, feedback, and release-note tools. · `frontend/src/features/tools/SettingsPage.tsx`
- [Admin UI](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/features/admin/AdminPage.tsx): admin console · Admin analytics, families, marketing, support, and user detail screens. · `frontend/src/features/admin/AdminPage.tsx`
- [Shared Lib](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/frontend/src/lib/api.ts): client infra · API client, query client, profile context, and finance helpers. · `frontend/src/lib/api.ts`

### Backend

FastAPI application, domain modules, and persistence

- [API App](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/main.py): FastAPI app · Backend application entrypoint and server assembly. · `backend/app/main.py`
- [V1 Router](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/api/v1/router.py): api composition · Versioned API router that wires module endpoints together. · `backend/app/api/v1/router.py`
- [Core](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/core/security.py): security & config · Shared backend concerns: config, JWT security, RBAC, email, and error handling. · `backend/app/core/security.py`
- [Modules](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/modules/__init__.py): domain slices · Business modules for auth, admin, accounts, budgets, dashboard, finance, goals, household, insurance, public, and wealth. · `backend/app/modules/__init__.py`
- [Persistence](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/db/session.py): ORM & session · SQLAlchemy models and database session management. · `backend/app/db/session.py`
- [Migrations](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/alembic/versions/0001_initial_schema.py): schema history · Alembic migrations for evolving family, budget, account, goal, and admin schema. · `backend/alembic/versions/0001_initial_schema.py`

### Runtime & Ops

Async jobs, database bootstrap, and supporting scripts

- [Workers](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/app/workers/celery_app.py): async jobs · Celery worker setup and notification background tasks. · `backend/app/workers/celery_app.py`
- [DB Tools](https://github.com/kaushikp020603/myarthiq/blob/vinayak/demo/backend/database/create_admin.py): bootstrap scripts · Database setup, seeding, admin creation, and SQLite/Postgres migration helpers. · `backend/database/create_admin.py`

## Connections

- Main → App: boots · React entrypoint initializes the application shell.
- App → Shell: uses · Authenticated product views are framed by the shell.
- App → Auth UI: routes · Public and onboarding paths flow into auth screens.
- App → Workspace: routes · Primary app navigation lands in the finance workspace.
- Workspace → Budgets: includes · Budgeting is one of the central workspace panels.
- Workspace → Accounts: includes · Accounts management is a core workspace area.
- Workspace → Transactions: includes · Transactions are surfaced as a primary workspace area.
- Workspace → Goals: includes · Goals are a first-class workspace feature.
- Workspace → Insurance: includes · Insurance views participate in the main product shell.
- Workspace → Portfolio: includes · Wealth and portfolio views are part of the core product.
- Workspace → Reports: includes · Reports summarize household financial activity.
- Workspace → Tools: includes · Settings, import, install, and onboarding utilities live here.
- Workspace → Admin UI: includes · Admin-only screens share the same frontend app.
- Workspace → Shared Lib: depends on · Feature pages rely on shared API, state, and finance helpers.
- Shared Lib → V1 Router: calls · Client requests target the versioned backend API.
- Auth UI → V1 Router: calls · Authentication flows use backend auth endpoints.
- API App → V1 Router: mounts · The FastAPI app composes the v1 router surface.
- V1 Router → Modules: dispatches to · Routers forward requests into feature modules.
- Modules → Core: guards with · Domain access is protected by auth, RBAC, and shared config.
- Modules → Persistence: persists via · Modules store and load data through ORM models and sessions.
- Persistence → Migrations: evolves with · Schema changes are tracked through Alembic migrations.
- Modules → Workers: enqueues · Some domain actions trigger background notification jobs.
- DB Tools → Persistence: initializes · Operational scripts prepare and seed the database.
- Core → Workers: supports · Email and security support async side effects and notifications.