# kridha24/homemind-ai architecture

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

- Interactive diagram: https://gitdiagram.com/kridha24/homemind-ai
- Repository: https://github.com/kridha24/homemind-ai

## Overview

HomeMind AI is a multi-tenant household operating system. A household member uses the web or mobile app to manage finances, bills, groceries, tasks, and family coordination; the app calls the REST backend, which applies household and role controls and serves domain features. The product also includes analytics, an AI copilot, encrypted messaging and calling, and background processing. The README documents these capabilities; source excerpts confirm selected authentication, task-sync, storage, and AI-service behavior, but do not expose every domain’s internal call chain.

Main entry points: [`apps/web/src/services/apiClient.ts`](https://github.com/kridha24/homemind-ai/blob/master/apps/web/src/services/apiClient.ts) (API client), [`apps/api/src/repositories/db.ts`](https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/repositories/db.ts) (Household database), [`apps/web/src/App.tsx`](https://github.com/kridha24/homemind-ai/blob/master/apps/web/src/App.tsx) (Web and mobile app), [`ai-service/app/main.py`](https://github.com/kridha24/homemind-ai/blob/master/ai-service/app/main.py) (AI service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Household clients"]
  node_webapp["Web and mobile app<br/>[App.tsx]"]
  node_api_client["API client<br/>[apiClient.ts]"]
  node_dashboard["Household dashboard<br/>[Dashboard.tsx]"]
end

subgraph group_api["API domains"]
  node_auth["Authentication and RBAC<br/>[auth.ts]"]
  node_finance["Finance tracking"]
  node_bills["Bills management<br/>[bill.service.ts]"]
  node_household["Household coordination"]
  node_groceries["Groceries and pantry"]
  node_tasks["Tasks and chores<br/>[useTasks.ts]"]
end

subgraph group_intelligence["AI and analytics"]
  node_analytics["Financial analytics"]
  node_copilot["Natural-language copilot<br/>[copilot.service.ts]"]
  node_ai_service["AI service<br/>[main.py]"]
  node_ocr["Receipt and pantry OCR<br/>[ocr.py]"]
  node_recipes["Recipe suggestions<br/>[recipes.py]"]
  node_forecasting["Forecasting and insights<br/>[forecasting.py]"]
end

subgraph group_operations["Platform operations"]
  node_database[("Household database<br/>[db.ts]")]
  node_worker["Background workers<br/>[index.ts]"]
  node_storage["Object storage"]
end

subgraph group_connection["Family connection"]
  node_communication["Encrypted messaging"]
  node_calling["WebRTC calling"]
  node_realtime["Realtime gateway<br/>[realtimeGateway.ts]"]
end

node_member(("Household member"))
node_ai_model(("AI capabilities"))

node_member -->|"manages household"| node_webapp
node_webapp -->|"requests data"| node_api_client
node_api_client -->|"sends bearer token"| node_auth
node_api_client -.->|"calls REST API"| node_finance
node_api_client -.->|"calls REST API"| node_bills
node_api_client -->|"calls task API"| node_tasks
node_api_client -.->|"calls REST API"| node_household
node_auth -->|"checks user"| node_database
node_webapp -->|"renders"| node_dashboard
node_dashboard -.->|"loads household view"| node_api_client
node_finance -.->|"reads and writes"| node_database
node_bills -.->|"reads and writes"| node_database
node_tasks -.->|"persists tasks"| node_database
node_groceries -.->|"uses API"| node_api_client
node_analytics -.->|"analyzes records"| node_database
node_copilot -->|"uses household data"| node_database
node_ai_service -->|"registers route"| node_ocr
node_ai_service -->|"registers route"| node_recipes
node_ai_service -->|"registers route"| node_forecasting
node_copilot -.->|"may request AI"| node_ai_service
node_ai_service -.->|"uses intelligence"| node_ai_model
node_worker -.->|"processes jobs"| node_database
node_webapp -.->|"uses family chat"| node_communication
node_webapp -.->|"starts calls"| node_calling
node_webapp -.->|"syncs live updates"| node_realtime
node_storage -.->|"stores object references"| node_database
node_member -.->|"exchanges messages"| node_communication

click node_webapp "https://github.com/kridha24/homemind-ai/blob/master/apps/web/src/App.tsx"
click node_api_client "https://github.com/kridha24/homemind-ai/blob/master/apps/web/src/services/apiClient.ts"
click node_auth "https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/middleware/auth.ts"
click node_finance "https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/modules/finance/transactions/transaction.service.ts"
click node_bills "https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/modules/bills/bill.service.ts"
click node_groceries "https://github.com/kridha24/homemind-ai/tree/master/apps/web/src/features/groceries"
click node_tasks "https://github.com/kridha24/homemind-ai/blob/master/apps/web/src/features/tasks/hooks/useTasks.ts"
click node_dashboard "https://github.com/kridha24/homemind-ai/blob/master/apps/web/src/pages/Dashboard.tsx"
click node_analytics "https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/modules/analytics/analytics.service.ts"
click node_copilot "https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/modules/copilot/copilot.service.ts"
click node_ai_service "https://github.com/kridha24/homemind-ai/blob/master/ai-service/app/main.py"
click node_ocr "https://github.com/kridha24/homemind-ai/blob/master/ai-service/app/routers/ocr.py"
click node_recipes "https://github.com/kridha24/homemind-ai/blob/master/ai-service/app/routers/recipes.py"
click node_forecasting "https://github.com/kridha24/homemind-ai/blob/master/ai-service/app/routers/forecasting.py"
click node_database "https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/repositories/db.ts"
click node_worker "https://github.com/kridha24/homemind-ai/blob/master/apps/worker/src/workers/index.ts"
click node_storage "https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/infrastructure/storage/objectStorageService.ts"
click node_communication "https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/modules/communication/secureMessagingService.ts"
click node_calling "https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/services/webrtcSignalingService.ts"
click node_realtime "https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/services/realtimeGateway.ts"

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_webapp,node_api_client,node_dashboard toneBlue
class node_auth,node_finance,node_bills,node_household,node_groceries,node_tasks toneAmber
class node_analytics,node_copilot,node_ai_service,node_ocr,node_recipes,node_forecasting toneMint
class node_database,node_worker,node_storage toneRose
class node_communication,node_calling,node_realtime,node_member,node_ai_model toneIndigo
```

## Components

### Household clients

- [Web and mobile app](https://github.com/kridha24/homemind-ai/blob/master/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [API client](https://github.com/kridha24/homemind-ai/blob/master/apps/web/src/services/apiClient.ts): `apps/web/src/services/apiClient.ts`
- [Household dashboard](https://github.com/kridha24/homemind-ai/blob/master/apps/web/src/pages/Dashboard.tsx): `apps/web/src/pages/Dashboard.tsx`

### API domains

- [Authentication and RBAC](https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/middleware/auth.ts): `apps/api/src/middleware/auth.ts`
- [Finance tracking](https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/modules/finance/transactions/transaction.service.ts): `apps/api/src/modules/finance/transactions/transaction.service.ts`
- [Bills management](https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/modules/bills/bill.service.ts): `apps/api/src/modules/bills/bill.service.ts`
- **Household coordination**
- [Groceries and pantry](https://github.com/kridha24/homemind-ai/tree/master/apps/web/src/features/groceries): `apps/web/src/features/groceries`
- [Tasks and chores](https://github.com/kridha24/homemind-ai/blob/master/apps/web/src/features/tasks/hooks/useTasks.ts): `apps/web/src/features/tasks/hooks/useTasks.ts`

### AI and analytics

- [Financial analytics](https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/modules/analytics/analytics.service.ts): `apps/api/src/modules/analytics/analytics.service.ts`
- [Natural-language copilot](https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/modules/copilot/copilot.service.ts): `apps/api/src/modules/copilot/copilot.service.ts`
- [AI service](https://github.com/kridha24/homemind-ai/blob/master/ai-service/app/main.py): `ai-service/app/main.py`
- [Receipt and pantry OCR](https://github.com/kridha24/homemind-ai/blob/master/ai-service/app/routers/ocr.py): `ai-service/app/routers/ocr.py`
- [Recipe suggestions](https://github.com/kridha24/homemind-ai/blob/master/ai-service/app/routers/recipes.py): `ai-service/app/routers/recipes.py`
- [Forecasting and insights](https://github.com/kridha24/homemind-ai/blob/master/ai-service/app/routers/forecasting.py): `ai-service/app/routers/forecasting.py`

### Platform operations

- [Household database](https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/repositories/db.ts): `apps/api/src/repositories/db.ts`
- [Background workers](https://github.com/kridha24/homemind-ai/blob/master/apps/worker/src/workers/index.ts): `apps/worker/src/workers/index.ts`
- [Object storage](https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/infrastructure/storage/objectStorageService.ts): `apps/api/src/infrastructure/storage/objectStorageService.ts`

### Family connection

- [Encrypted messaging](https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/modules/communication/secureMessagingService.ts): `apps/api/src/modules/communication/secureMessagingService.ts`
- [WebRTC calling](https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/services/webrtcSignalingService.ts): `apps/api/src/services/webrtcSignalingService.ts`
- [Realtime gateway](https://github.com/kridha24/homemind-ai/blob/master/apps/api/src/services/realtimeGateway.ts): `apps/api/src/services/realtimeGateway.ts`

### Other components

- **Household member**
- **AI capabilities**

## Connections

- Household member → Web and mobile app: manages household (evidence: `README.md`)
- Web and mobile app → API client: requests data (evidence: `apps/web/src/App.tsx`)
- API client → Authentication and RBAC: sends bearer token (evidence: `apps/web/src/services/apiClient.ts`)
- API client → Finance tracking: calls REST API
- API client → Bills management: calls REST API
- API client → Tasks and chores: calls task API (evidence: `apps/web/src/features/tasks/hooks/useTasks.ts`)
- API client → Household coordination: calls REST API
- Authentication and RBAC → Household database: checks user (evidence: `apps/api/src/middleware/auth.ts`)
- Web and mobile app → Household dashboard: renders (evidence: `apps/web/src/App.tsx`)
- Household dashboard → API client: loads household view
- Finance tracking → Household database: reads and writes
- Bills management → Household database: reads and writes
- Tasks and chores → Household database: persists tasks
- Groceries and pantry → API client: uses API
- Financial analytics → Household database: analyzes records
- Natural-language copilot → Household database: uses household data (evidence: `apps/api/src/modules/copilot/copilot.controller.ts`)
- AI service → Receipt and pantry OCR: registers route (evidence: `ai-service/app/main.py`)
- AI service → Recipe suggestions: registers route (evidence: `ai-service/app/main.py`)
- AI service → Forecasting and insights: registers route (evidence: `ai-service/app/main.py`)
- Natural-language copilot → AI service: may request AI
- AI service → AI capabilities: uses intelligence
- Background workers → Household database: processes jobs
- Web and mobile app → Encrypted messaging: uses family chat
- Web and mobile app → WebRTC calling: starts calls
- Web and mobile app → Realtime gateway: syncs live updates
- Object storage → Household database: stores object references
- Household member → Encrypted messaging: exchanges messages
