# aad1tshah1/ai_notes architecture

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

- Interactive diagram: https://gitdiagram.com/aad1tshah1/ai_notes
- Repository: https://github.com/aad1tshah1/ai_notes
- Video tour (about a minute): https://gitdiagram.com/aad1tshah1/ai_notes/video

## Overview

AI Notes is a web application for turning uploaded meeting audio into searchable notes. Users register or log in, upload a recording, receive a job ID, poll for progress, and retrieve the completed note. The backend handles authentication and API requests, while a Celery worker transcribes audio with Whisper, summarizes it with Claude, and persists job and note data. The README documents the queue and product capabilities; some frontend and API wiring is not sampled, so those links follow documented behavior rather than inspected implementations.

Main entry points: [`backend/worker/tasks.py`](https://github.com/aad1tshah1/ai_notes/blob/main/backend/worker/tasks.py) (Note worker), [`backend/api/notes.py`](https://github.com/aad1tshah1/ai_notes/blob/main/backend/api/notes.py) (Notes routes), [`backend/core/database.py`](https://github.com/aad1tshah1/ai_notes/blob/main/backend/core/database.py) (Database access), [`frontend/src/app`](https://github.com/aad1tshah1/ai_notes/tree/main/frontend/src/app) (Application pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_frontend_pages["Application pages"]
  node_auth_ui["Auth service<br/>[auth.ts]"]
  node_jobs_ui["Jobs service<br/>[jobs.ts]"]
  node_notes_ui["Notes service<br/>[notes.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and identity"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_auth_api["Auth routes<br/>[auth.py]"]
  node_notes_api["Notes routes<br/>[notes.py]"]
  node_jobs_api["Job routes<br/>[jobs.py]"]
  node_auth_service["Auth service<br/>[auth_service.py]"]
end

subgraph group_processing["Async processing"]
  node_celery["Celery queue<br/>[celery_app.py]"]
  node_worker["Note worker<br/>[tasks.py]"]
  node_transcription["Transcription"]
  node_summarisation["Summarisation"]
end

subgraph group_persistence["Persistence"]
  node_database_access["Database access<br/>[database.py]"]
  node_job_repository["Job repository<br/>[job_repository.py]"]
  node_note_repository["Note repository<br/>[note_repository.py]"]
  node_user_repository["User repository<br/>[user_repository.py]"]
  node_postgres[("PostgreSQL")]
end

node_user(("User"))
node_whisper["Whisper"]
node_claude["Anthropic Claude"]

node_user -->|"uses"| node_frontend_pages
node_frontend_pages -->|"registers, logs in"| node_auth_ui
node_frontend_pages -->|"uploads, polls"| node_jobs_ui
node_frontend_pages -->|"retrieves notes"| node_notes_ui
node_auth_ui -->|"uses API URL"| node_api_client
node_jobs_ui -->|"uses API URL"| node_api_client
node_notes_ui -->|"uses API URL"| node_api_client
node_api_client -->|"sends requests"| node_fastapi
node_fastapi -->|"dispatches"| node_auth_api
node_fastapi -->|"dispatches"| node_notes_api
node_fastapi -->|"dispatches"| node_jobs_api
node_auth_api -->|"hashes, verifies, issues JWT"| node_auth_service
node_auth_api -->|"reads, creates users"| node_user_repository
node_notes_api -->|"reads, writes notes"| node_note_repository
node_notes_api -->|"creates jobs"| node_job_repository
node_notes_api -->|"enqueues task"| node_celery
node_jobs_api -->|"reads job status"| node_job_repository
node_celery -->|"dispatches task"| node_worker
node_worker -->|"updates job status"| node_job_repository
node_worker -->|"transcribes audio"| node_transcription
node_transcription -->|"transcribes"| node_whisper
node_worker -->|"generates notes"| node_summarisation
node_summarisation -->|"requests summary"| node_claude
node_worker -->|"saves note"| node_note_repository
node_auth_api -->|"gets DB session"| node_database_access
node_notes_api -->|"gets DB session"| node_database_access
node_jobs_api -->|"gets DB session"| node_database_access
node_worker -->|"opens session"| node_database_access
node_job_repository -->|"reads, writes jobs"| node_postgres
node_note_repository -->|"reads, writes notes"| node_postgres
node_user_repository -->|"reads, writes users"| node_postgres
node_database_access -->|"connects"| node_postgres

click node_frontend_pages "https://github.com/aad1tshah1/ai_notes/tree/main/frontend/src/app"
click node_auth_ui "https://github.com/aad1tshah1/ai_notes/blob/main/frontend/src/services/auth.ts"
click node_jobs_ui "https://github.com/aad1tshah1/ai_notes/blob/main/frontend/src/services/jobs.ts"
click node_notes_ui "https://github.com/aad1tshah1/ai_notes/blob/main/frontend/src/services/notes.ts"
click node_api_client "https://github.com/aad1tshah1/ai_notes/blob/main/frontend/src/lib/api.ts"
click node_fastapi "https://github.com/aad1tshah1/ai_notes/blob/main/backend/main.py"
click node_auth_api "https://github.com/aad1tshah1/ai_notes/blob/main/backend/api/auth.py"
click node_notes_api "https://github.com/aad1tshah1/ai_notes/blob/main/backend/api/notes.py"
click node_jobs_api "https://github.com/aad1tshah1/ai_notes/blob/main/backend/api/jobs.py"
click node_auth_service "https://github.com/aad1tshah1/ai_notes/blob/main/backend/services/auth_service.py"
click node_celery "https://github.com/aad1tshah1/ai_notes/blob/main/backend/worker/celery_app.py"
click node_worker "https://github.com/aad1tshah1/ai_notes/blob/main/backend/worker/tasks.py"
click node_transcription "https://github.com/aad1tshah1/ai_notes/blob/main/backend/services/transcription_service.py"
click node_summarisation "https://github.com/aad1tshah1/ai_notes/blob/main/backend/services/summarisation_service.py"
click node_database_access "https://github.com/aad1tshah1/ai_notes/blob/main/backend/core/database.py"
click node_job_repository "https://github.com/aad1tshah1/ai_notes/blob/main/backend/repositories/job_repository.py"
click node_note_repository "https://github.com/aad1tshah1/ai_notes/blob/main/backend/repositories/note_repository.py"
click node_user_repository "https://github.com/aad1tshah1/ai_notes/blob/main/backend/repositories/user_repository.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_pages,node_auth_ui,node_jobs_ui,node_notes_ui,node_api_client,node_user toneBlue
class node_fastapi,node_auth_api,node_notes_api,node_jobs_api,node_auth_service toneAmber
class node_celery,node_worker,node_transcription,node_summarisation toneMint
class node_database_access,node_job_repository,node_note_repository,node_user_repository,node_postgres toneRose
class node_whisper,node_claude toneIndigo
```

## Components

### Web client

- [Application pages](https://github.com/aad1tshah1/ai_notes/tree/main/frontend/src/app): `frontend/src/app`
- [Auth service](https://github.com/aad1tshah1/ai_notes/blob/main/frontend/src/services/auth.ts): `frontend/src/services/auth.ts`
- [Jobs service](https://github.com/aad1tshah1/ai_notes/blob/main/frontend/src/services/jobs.ts): `frontend/src/services/jobs.ts`
- [Notes service](https://github.com/aad1tshah1/ai_notes/blob/main/frontend/src/services/notes.ts): `frontend/src/services/notes.ts`
- [API client](https://github.com/aad1tshah1/ai_notes/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and identity

- [FastAPI app](https://github.com/aad1tshah1/ai_notes/blob/main/backend/main.py): `backend/main.py`
- [Auth routes](https://github.com/aad1tshah1/ai_notes/blob/main/backend/api/auth.py): `backend/api/auth.py`
- [Notes routes](https://github.com/aad1tshah1/ai_notes/blob/main/backend/api/notes.py): `backend/api/notes.py`
- [Job routes](https://github.com/aad1tshah1/ai_notes/blob/main/backend/api/jobs.py): `backend/api/jobs.py`
- [Auth service](https://github.com/aad1tshah1/ai_notes/blob/main/backend/services/auth_service.py): `backend/services/auth_service.py`

### Async processing

- [Celery queue](https://github.com/aad1tshah1/ai_notes/blob/main/backend/worker/celery_app.py): `backend/worker/celery_app.py`
- [Note worker](https://github.com/aad1tshah1/ai_notes/blob/main/backend/worker/tasks.py): `backend/worker/tasks.py`
- [Transcription](https://github.com/aad1tshah1/ai_notes/blob/main/backend/services/transcription_service.py): `backend/services/transcription_service.py`
- [Summarisation](https://github.com/aad1tshah1/ai_notes/blob/main/backend/services/summarisation_service.py): `backend/services/summarisation_service.py`

### Persistence

- [Database access](https://github.com/aad1tshah1/ai_notes/blob/main/backend/core/database.py): `backend/core/database.py`
- [Job repository](https://github.com/aad1tshah1/ai_notes/blob/main/backend/repositories/job_repository.py): `backend/repositories/job_repository.py`
- [Note repository](https://github.com/aad1tshah1/ai_notes/blob/main/backend/repositories/note_repository.py): `backend/repositories/note_repository.py`
- [User repository](https://github.com/aad1tshah1/ai_notes/blob/main/backend/repositories/user_repository.py): `backend/repositories/user_repository.py`
- **PostgreSQL**

### Other components

- **User**
- **Whisper**
- **Anthropic Claude**

## Connections

- User → Application pages: uses
- Application pages → Auth service: registers, logs in
- Application pages → Jobs service: uploads, polls
- Application pages → Notes service: retrieves notes
- Auth service → API client: uses API URL
- Jobs service → API client: uses API URL
- Notes service → API client: uses API URL
- API client → FastAPI app: sends requests
- FastAPI app → Auth routes: dispatches
- FastAPI app → Notes routes: dispatches
- FastAPI app → Job routes: dispatches
- Auth routes → Auth service: hashes, verifies, issues JWT
- Auth routes → User repository: reads, creates users
- Notes routes → Note repository: reads, writes notes
- Notes routes → Job repository: creates jobs
- Notes routes → Celery queue: enqueues task
- Job routes → Job repository: reads job status
- Celery queue → Note worker: dispatches task
- Note worker → Job repository: updates job status
- Note worker → Transcription: transcribes audio
- Transcription → Whisper: transcribes
- Note worker → Summarisation: generates notes
- Summarisation → Anthropic Claude: requests summary
- Note worker → Note repository: saves note
- Auth routes → Database access: gets DB session
- Notes routes → Database access: gets DB session
- Job routes → Database access: gets DB session
- Note worker → Database access: opens session
- Job repository → PostgreSQL: reads, writes jobs
- Note repository → PostgreSQL: reads, writes notes
- User repository → PostgreSQL: reads, writes users
- Database access → PostgreSQL: connects