# development-2-product/ai-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/development-2-product/ai-assistant
- Repository: https://github.com/development-2-product/ai-assistant

## Overview

IA Mode is an Android personal assistant backed by a stateless FastAPI/Gemini service. Its principal workflow is: phone events or mailbox updates arrive, on-device policy decides whether approval is needed, the backend analyzes or drafts text, and the app sends approved replies or missed-call SMS. Separate workflows cover email intelligence and job tracking. The README documents these product capabilities; source-index references support several internal links, but many Android runtime paths were not excerpted, so unverified wiring is omitted.

Main entry points: [`frontend/app/src/main/java/com/iamode/app/data/mail/MailIntelligenceRepository.kt`](https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/data/mail/MailIntelligenceRepository.kt) (Mail intelligence workflow), [`frontend/app/src/main/java/com/iamode/app/domain/usecase`](https://github.com/development-2-product/ai-assistant/tree/main/frontend/app/src/main/java/com/iamode/app/domain/usecase) (Conversation handling), [`frontend/app/src/main/java/com/iamode/app/data/ai/AiRepositoryImpl.kt`](https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/data/ai/AiRepositoryImpl.kt) (AI API client), [`frontend/app/src/main/java/com/iamode/app/data/gmail/GmailRepository.kt`](https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/data/gmail/GmailRepository.kt) (Gmail and Outlook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android assistant"]
  node_app["App shell<br/>[MainActivity.kt]"]
  node_event_ingress["Message and call intake"]
  node_message_flow["Conversation handling"]
  node_reply_policy["Reply policy<br/>[ReplyPolicy.kt]"]
  node_ai_client["AI API client"]
  node_senders["Reply and SMS delivery<br/>[SmsSender.kt]"]
end

subgraph group_mail["Email intelligence"]
  node_mail_ui["Mail review screens"]
  node_mail_intel["Mail intelligence workflow"]
  node_mail_policy["Mail action policy"]
  node_mail_providers["Gmail and Outlook<br/>[GmailRepository.kt]"]
  node_documents["Document sources<br/>[DocumentSources.kt]"]
  node_job_tracker["Job tracking"]
end

subgraph group_backend["AI backend"]
  node_api["Versioned API<br/>[router.py]"]
  node_assistant_service["Assistant workflows<br/>[assistant.py]"]
  node_gemini["Gemini client<br/>[gemini_client.py]"]
end

subgraph group_state["Phone state"]
  node_local_state[("Local database")]
  node_diagnostics["Diagnostics<br/>[DiagnosticsLog.kt]"]
end

node_user(("User"))
node_models{{"Gemini service"}}
node_gmail_service{{"Gmail service"}}
node_outlook_service{{"Microsoft Graph"}}
node_phone_events{{"Phone and notifications"}}

node_user -->|"uses"| node_app
node_phone_events -->|"delivers events"| node_event_ingress
node_event_ingress -.->|"processes"| node_message_flow
node_message_flow -->|"checks safety"| node_reply_policy
node_message_flow -.->|"requests drafts"| node_ai_client
node_ai_client -.->|"calls"| node_api
node_api -->|"routes requests"| node_assistant_service
node_assistant_service -->|"generates text"| node_gemini
node_gemini -->|"requests generation"| node_models
node_reply_policy -->|"permits delivery"| node_senders
node_mail_ui -->|"reviews actions"| node_mail_intel
node_mail_intel -->|"checks actions"| node_mail_policy
node_mail_intel -->|"fetches mail"| node_mail_providers
node_mail_intel -->|"resolves files"| node_documents
node_mail_intel -.->|"requests drafts"| node_api
node_mail_providers -.->|"reads and sends"| node_gmail_service
node_mail_providers -.->|"reads and sends"| node_outlook_service
node_mail_intel -->|"stores workflow"| node_local_state
node_job_tracker -->|"stores applications"| node_local_state
node_ai_client -->|"records activity"| node_diagnostics
node_app -->|"starts sync"| node_mail_intel

click node_app "https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/MainActivity.kt"
click node_event_ingress "https://github.com/development-2-product/ai-assistant/tree/main/frontend/app/src/main/java/com/iamode/app/service"
click node_message_flow "https://github.com/development-2-product/ai-assistant/tree/main/frontend/app/src/main/java/com/iamode/app/domain/usecase"
click node_reply_policy "https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/domain/policy/ReplyPolicy.kt"
click node_ai_client "https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/data/ai/AiRepositoryImpl.kt"
click node_senders "https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/service/sms/SmsSender.kt"
click node_mail_ui "https://github.com/development-2-product/ai-assistant/tree/main/frontend/app/src/main/java/com/iamode/app/ui/feature/mail"
click node_mail_intel "https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/data/mail/MailIntelligenceRepository.kt"
click node_mail_policy "https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/domain/mail/MailPolicyEngine.kt"
click node_mail_providers "https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/data/gmail/GmailRepository.kt"
click node_documents "https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/data/mail/DocumentSources.kt"
click node_job_tracker "https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/data/jobs/JobTrackerRepository.kt"
click node_local_state "https://github.com/development-2-product/ai-assistant/tree/main/frontend/app/src/main/java/com/iamode/app/core/database"
click node_diagnostics "https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/core/diagnostics/DiagnosticsLog.kt"
click node_api "https://github.com/development-2-product/ai-assistant/blob/main/backend/app/api/v1/router.py"
click node_assistant_service "https://github.com/development-2-product/ai-assistant/blob/main/backend/app/services/assistant.py"
click node_gemini "https://github.com/development-2-product/ai-assistant/blob/main/backend/app/services/gemini_client.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_app,node_event_ingress,node_message_flow,node_reply_policy,node_ai_client,node_senders,node_user toneBlue
class node_mail_ui,node_mail_intel,node_mail_policy,node_mail_providers,node_documents,node_job_tracker toneAmber
class node_api,node_assistant_service,node_gemini toneMint
class node_local_state,node_diagnostics toneRose
class node_models,node_gmail_service,node_outlook_service,node_phone_events toneIndigo
```

## Components

### Android assistant

- [App shell](https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/MainActivity.kt): `frontend/app/src/main/java/com/iamode/app/MainActivity.kt`
- [Message and call intake](https://github.com/development-2-product/ai-assistant/tree/main/frontend/app/src/main/java/com/iamode/app/service): `frontend/app/src/main/java/com/iamode/app/service`
- [Conversation handling](https://github.com/development-2-product/ai-assistant/tree/main/frontend/app/src/main/java/com/iamode/app/domain/usecase): `frontend/app/src/main/java/com/iamode/app/domain/usecase`
- [Reply policy](https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/domain/policy/ReplyPolicy.kt): `frontend/app/src/main/java/com/iamode/app/domain/policy/ReplyPolicy.kt`
- [AI API client](https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/data/ai/AiRepositoryImpl.kt): `frontend/app/src/main/java/com/iamode/app/data/ai/AiRepositoryImpl.kt`
- [Reply and SMS delivery](https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/service/sms/SmsSender.kt): `frontend/app/src/main/java/com/iamode/app/service/sms/SmsSender.kt`

### Email intelligence

- [Mail review screens](https://github.com/development-2-product/ai-assistant/tree/main/frontend/app/src/main/java/com/iamode/app/ui/feature/mail): `frontend/app/src/main/java/com/iamode/app/ui/feature/mail`
- [Mail intelligence workflow](https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/data/mail/MailIntelligenceRepository.kt): `frontend/app/src/main/java/com/iamode/app/data/mail/MailIntelligenceRepository.kt`
- [Mail action policy](https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/domain/mail/MailPolicyEngine.kt): `frontend/app/src/main/java/com/iamode/app/domain/mail/MailPolicyEngine.kt`
- [Gmail and Outlook](https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/data/gmail/GmailRepository.kt): `frontend/app/src/main/java/com/iamode/app/data/gmail/GmailRepository.kt`
- [Document sources](https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/data/mail/DocumentSources.kt): `frontend/app/src/main/java/com/iamode/app/data/mail/DocumentSources.kt`
- [Job tracking](https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/data/jobs/JobTrackerRepository.kt): `frontend/app/src/main/java/com/iamode/app/data/jobs/JobTrackerRepository.kt`

### AI backend

- [Versioned API](https://github.com/development-2-product/ai-assistant/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Assistant workflows](https://github.com/development-2-product/ai-assistant/blob/main/backend/app/services/assistant.py): `backend/app/services/assistant.py`
- [Gemini client](https://github.com/development-2-product/ai-assistant/blob/main/backend/app/services/gemini_client.py): `backend/app/services/gemini_client.py`

### Phone state

- [Local database](https://github.com/development-2-product/ai-assistant/tree/main/frontend/app/src/main/java/com/iamode/app/core/database): `frontend/app/src/main/java/com/iamode/app/core/database`
- [Diagnostics](https://github.com/development-2-product/ai-assistant/blob/main/frontend/app/src/main/java/com/iamode/app/core/diagnostics/DiagnosticsLog.kt): `frontend/app/src/main/java/com/iamode/app/core/diagnostics/DiagnosticsLog.kt`

### Other components

- **User**
- **Gemini service**
- **Gmail service**
- **Microsoft Graph**
- **Phone and notifications**

## Connections

- User → App shell: uses (evidence: `README.md`)
- Phone and notifications → Message and call intake: delivers events (evidence: `README.md`)
- Message and call intake → Conversation handling: processes (evidence: `frontend/app/src/main/java/com/iamode/app/service/worker/AiRetryWorker.kt`)
- Conversation handling → Reply policy: checks safety (evidence: `README.md`)
- Conversation handling → AI API client: requests drafts
- AI API client → Versioned API: calls
- Versioned API → Assistant workflows: routes requests (evidence: `backend/app/api/v1/router.py`)
- Assistant workflows → Gemini client: generates text (evidence: `backend/app/api/deps.py`)
- Gemini client → Gemini service: requests generation (evidence: `backend/app/services/gemini_client.py`)
- Reply policy → Reply and SMS delivery: permits delivery (evidence: `README.md`)
- Mail review screens → Mail intelligence workflow: reviews actions (evidence: `frontend/app/src/main/java/com/iamode/app/ui/feature/mail/ReplyReviewScreen.kt`)
- Mail intelligence workflow → Mail action policy: checks actions (evidence: `frontend/app/src/main/java/com/iamode/app/data/mail/MailIntelligenceRepository.kt`)
- Mail intelligence workflow → Gmail and Outlook: fetches mail (evidence: `frontend/app/src/main/java/com/iamode/app/data/mail/MailIntelligenceRepository.kt`)
- Mail intelligence workflow → Document sources: resolves files (evidence: `frontend/app/src/main/java/com/iamode/app/data/mail/MailIntelligenceRepository.kt`)
- Mail intelligence workflow → Versioned API: requests drafts
- Gmail and Outlook → Gmail service: reads and sends
- Gmail and Outlook → Microsoft Graph: reads and sends
- Mail intelligence workflow → Local database: stores workflow (evidence: `frontend/app/src/main/java/com/iamode/app/data/mail/MailIntelligenceRepository.kt`)
- Job tracking → Local database: stores applications (evidence: `frontend/app/src/main/java/com/iamode/app/data/jobs/JobTrackerRepository.kt`)
- AI API client → Diagnostics: records activity (evidence: `frontend/app/src/main/java/com/iamode/app/data/ai/AiRepositoryImpl.kt`)
- App shell → Mail intelligence workflow: starts sync (evidence: `frontend/app/src/main/java/com/iamode/app/MainActivity.kt`)