# dothanhbao1805/meeting_assistant_be architecture

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

- Interactive diagram: https://gitdiagram.com/dothanhbao1805/meeting_assistant_be
- Repository: https://github.com/dothanhbao1805/meeting_assistant_be

## Overview

1. This repository is a microservice backend for a “Meeting Assistant” product. The code is split into independently deployed Python services, each with its own FastAPI-style app structure, database layer, schemas, repositories, and service layer. A `docker-compose.yml` and per-service Dockerfiles indicate containerized local/runtime orchestration.

2. The edge entry point is `services/api-gateway`, which is a thin gateway layer in front of the backend. It likely receives client traffic and forwards it to the domain services rather than containing business logic itself.

3. Identity is isolated in `services/auth-service`. It owns users and refresh tokens, with routers for auth, user management, and internal service-to-service checks. This service is the security boundary for authentication and token lifecycle.

4. Core company and workspace data live in `services/company-service`. It manages companies, members, vocabulary, transcription corrections, Trello board settings, and Google Calendar settings. It also includes utility code for voice embeddings, which suggests member identification or speaker-related matching is part of the company domain.

5. Meeting metadata and file storage are handled by `services/meeting-service`. It stores meetings, meeting participants, and meeting files, and exposes both public and internal routers. This service is the canonical source for meeting records and uploaded assets before downstream transcription or analysis begins.

6. Speech-to-text processing is centered in `services/transcription-service`. It manages transcription jobs, transcripts, and utterances, and integrates with a Deepgram client plus webhook handling. It also has background workers and Redis support, indicating asynchronous job processing and webhook-driven state transitions. Utilities such as speaker matching and audio cropping show that this service does more than raw transcription; it also attempts diarization/alignment and post-processing.

7. Higher-level AI summarization and task extraction are in `services/ai-analysis-service`. It owns analysis jobs, meeting summaries, and extracted tasks, and depends on clients for meeting, participant, utterance, and speaker data. It also includes a Groq client, deadline parsing, assignee mapping, an event publisher, and a transcription subscriber, so this service consumes transcription output and turns it into structured meeting insights and action items.

8. `services/ai-service` is a separate AI utility service with upload and summarize routers, plus Whisper and Groq integrations. Compared with `ai-analysis-service`, it looks more like a narrower AI helper service for audio upload/transcription/summarization primitives rather than full meeting analytics.

9. Cross-system synchronization lives in `services/integration-service`. It stores calendar events, sync queues, and Trello sync logs, and includes workers plus Redis. It connects outward to Google Calendar and Trello and inward to company data via a company client, making it the integration boundary for external system sync and background reconciliation.

10. The system uses an event/worker pattern in several places. Transcription and analysis are not purely synchronous HTTP workflows; they involve Redis-backed processing, subscribers, and workers. That suggests a pipeline like: meeting/audio data enters the meeting and transcription services, transcription output is published/consumed, analysis produces summaries/tasks, and integration jobs sync those results to external tools.

11. Persistence is service-owned rather than shared. Most services have their own `db/database.py`, SQLAlchemy-style models, Alembic migrations, and repositories. This implies separate databases or at least separate schemas per service, with the repository layer acting as the main persistence boundary inside each service.

12. A useful architecture diagram should show the main domain boundaries as: identity, company/workspace, meetings/files, transcription, AI analysis, generic AI utilities, and external integrations. The external systems that materially affect behavior are Groq, Whisper, Deepgram, Google Calendar, Trello, Redis, and Cloudinary.

13. The repeated internal structure across services is intentional: `routers` expose HTTP APIs, `services` hold business logic, `repositories` isolate persistence, `schemas` define API payloads, and `models` map database entities. This makes the repo a federated set of backend services rather than a single monolith.

Main entry points: [`services/api-gateway/main.py`](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/api-gateway/main.py) (API Gateway), [`services/integration-service/app/routers/sync.py`](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/integration-service/app/routers/sync.py) (Sync API), [`services/transcription-service/app/routers/job.py`](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/transcription-service/app/routers/job.py) (Transcribe API), [`services/company-service/app/routers/company.py`](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/company-service/app/routers/company.py) (Company API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge/API"]
  node_api_gateway["API Gateway<br/>edge proxy<br/>[main.py]"]
end

subgraph group_identity["Identity"]
  node_auth_service["Auth API<br/>auth service<br/>[auth.py]"]
  node_auth_logic["Auth Logic<br/>auth domain<br/>[auth_service.py]"]
  node_auth_models[("Users<br/>auth models<br/>[user.py]")]
end

subgraph group_workspace["Company"]
  node_company_api["Company API<br/>workspace service<br/>[company.py]"]
  node_member_voice["Member Voice<br/>matching service"]
  node_company_models[("Company Data<br/>workspace models<br/>[company.py]")]
end

subgraph group_meetings["Meetings"]
  node_meeting_api["Meeting API<br/>meeting service<br/>[meeting.py]"]
  node_meeting_files["Meeting Files<br/>file service"]
  node_meeting_models[("Meeting Data<br/>meeting models<br/>[meeting.py]")]
end

subgraph group_transcription["Transcription"]
  node_transcription_api["Transcribe API<br/>transcription service<br/>[job.py]"]
  node_transcription_worker["Transcribe Worker<br/>async worker"]
  node_deepgram_client["Deepgram<br/>speech client<br/>[deepgram_client.py]"]
  node_transcription_models[("Transcription Data<br/>transcription models")]
end

subgraph group_analysis["AI Analysis"]
  node_analysis_api["Analysis API<br/>analysis service<br/>[analysis.py]"]
  node_analysis_subscriber["Transcription Sub<br/>event subscriber"]
  node_analysis_ai["Groq Analysis<br/>llm service<br/>[groq_service.py]"]
  node_analysis_models[("Analysis Data<br/>analysis models<br/>[analysis_job.py]")]
end

subgraph group_aiutils["AI Utils"]
  node_ai_utils_api["AI API<br/>ai helper<br/>[upload.py]"]
  node_ai_utils_models["AI Models<br/>ai helper<br/>[whisper_service.py]"]
end

subgraph group_integration["Integrations"]
  node_integration_api["Sync API<br/>integration service<br/>[sync.py]"]
  node_integration_worker["Integration Worker<br/>async worker"]
  node_integration_models[("Sync Data<br/>integration models<br/>[sync_queue.py]")]
end

subgraph group_external["External Systems"]
  node_redis[("Redis<br/>infra cache")]
  node_google_calendar(("Google Calendar<br/>external api"))
  node_trello(("Trello<br/>external api"))
  node_cloudinary(("Cloudinary<br/>media store"))
  node_groq(("Groq<br/>llm api"))
  node_whisper(("Whisper<br/>speech model"))
end

node_api_gateway -->|"routes to"| node_auth_service
node_api_gateway -->|"routes to"| node_company_api
node_api_gateway -->|"routes to"| node_meeting_api
node_api_gateway -->|"routes to"| node_transcription_api
node_api_gateway -->|"routes to"| node_analysis_api
node_auth_service -->|"uses"| node_auth_logic
node_auth_logic -->|"persists"| node_auth_models
node_company_api -->|"uses"| node_member_voice
node_member_voice -->|"persists"| node_company_models
node_company_api -->|"stores"| node_cloudinary
node_meeting_api -->|"uses"| node_meeting_files
node_meeting_files -->|"persists"| node_meeting_models
node_transcription_api -->|"calls"| node_deepgram_client
node_transcription_api -->|"enqueues"| node_transcription_worker
node_transcription_worker -->|"uses"| node_redis
node_transcription_worker -->|"updates"| node_transcription_models
node_transcription_api -->|"persists"| node_transcription_models
node_analysis_api -->|"uses"| node_analysis_ai
node_analysis_api -->|"consumes"| node_analysis_subscriber
node_analysis_subscriber -->|"publishes to"| node_groq
node_analysis_ai -->|"persists"| node_analysis_models
node_ai_utils_api -->|"uses"| node_ai_utils_models
node_ai_utils_models -->|"calls"| node_whisper
node_ai_utils_models -->|"calls"| node_groq
node_integration_api -->|"queues"| node_integration_worker
node_integration_worker -->|"uses"| node_redis
node_integration_api -->|"persists"| node_integration_models
node_integration_api -->|"syncs"| node_google_calendar
node_integration_api -->|"syncs"| node_trello
node_integration_api -->|"reads"| node_company_api

click node_api_gateway "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/api-gateway/main.py"
click node_auth_service "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/auth-service/app/routers/auth.py"
click node_auth_logic "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/auth-service/app/services/auth_service.py"
click node_auth_models "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/auth-service/app/models/user.py"
click node_company_api "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/company-service/app/routers/company.py"
click node_member_voice "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/company-service/app/services/member_voice_service.py"
click node_company_models "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/company-service/app/models/company.py"
click node_meeting_api "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/meeting-service/app/routers/meeting.py"
click node_meeting_files "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/meeting-service/app/services/meeting_file_service.py"
click node_meeting_models "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/meeting-service/app/models/meeting.py"
click node_transcription_api "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/transcription-service/app/routers/job.py"
click node_transcription_worker "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/transcription-service/app/workers/auto_resolve_worker.py"
click node_deepgram_client "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/transcription-service/app/services/deepgram_client.py"
click node_transcription_models "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/transcription-service/app/models/transcription_job.py"
click node_analysis_api "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/ai-analysis-service/app/routers/analysis.py"
click node_analysis_subscriber "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/ai-analysis-service/app/subscribers/transcription_subscriber.py"
click node_analysis_ai "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/ai-analysis-service/app/services/groq_service.py"
click node_analysis_models "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/ai-analysis-service/app/models/analysis_job.py"
click node_ai_utils_api "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/ai-service/app/routers/upload.py"
click node_ai_utils_models "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/ai-service/app/services/whisper_service.py"
click node_integration_api "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/integration-service/app/routers/sync.py"
click node_integration_worker "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/integration-service/app/workers/integration_worker.py"
click node_integration_models "https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/integration-service/app/models/sync_queue.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_api_gateway,node_ai_utils_api,node_ai_utils_models toneBlue
class node_auth_service,node_auth_logic,node_auth_models,node_integration_api,node_integration_worker,node_integration_models toneAmber
class node_company_api,node_member_voice,node_company_models,node_redis,node_google_calendar,node_trello,node_cloudinary,node_groq,node_whisper toneMint
class node_meeting_api,node_meeting_files,node_meeting_models toneRose
class node_transcription_api,node_transcription_worker,node_deepgram_client,node_transcription_models toneIndigo
class node_analysis_api,node_analysis_subscriber,node_analysis_ai,node_analysis_models toneTeal
```

## Components

### Edge/API

Client entry and request routing

- [API Gateway](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/api-gateway/main.py): edge proxy · Thin front door for backend services · `services/api-gateway/main.py`

### Identity

Authentication and user lifecycle

- [Auth API](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/auth-service/app/routers/auth.py): auth service · Authentication and user endpoints · `services/auth-service/app/routers/auth.py`
- [Auth Logic](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/auth-service/app/services/auth_service.py): auth domain · Token and user orchestration · `services/auth-service/app/services/auth_service.py`
- [Users](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/auth-service/app/models/user.py): auth models · Users and refresh tokens · `services/auth-service/app/models/user.py`

### Company

Companies, members, and workspace settings

- [Company API](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/company-service/app/routers/company.py): workspace service · Companies, members, and settings · `services/company-service/app/routers/company.py`
- [Member Voice](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/company-service/app/services/member_voice_service.py): matching service · Voice embedding and speaker matching · `services/company-service/app/services/member_voice_service.py`
- [Company Data](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/company-service/app/models/company.py): workspace models · Companies, members, vocabulary, and board settings · `services/company-service/app/models/company.py`

### Meetings

Meeting records and uploaded files

- [Meeting API](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/meeting-service/app/routers/meeting.py): meeting service · Meeting and file endpoints · `services/meeting-service/app/routers/meeting.py`
- [Meeting Files](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/meeting-service/app/services/meeting_file_service.py): file service · Meeting file storage and handling · `services/meeting-service/app/services/meeting_file_service.py`
- [Meeting Data](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/meeting-service/app/models/meeting.py): meeting models · Meetings, participants, and files · `services/meeting-service/app/models/meeting.py`

### Transcription

Audio jobs, transcripts, and webhook processing

- [Transcribe API](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/transcription-service/app/routers/job.py): transcription service · Jobs, transcripts, utterances, and webhooks · `services/transcription-service/app/routers/job.py`
- [Transcribe Worker](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/transcription-service/app/workers/auto_resolve_worker.py): async worker · Background job and auto-resolve processing · `services/transcription-service/app/workers/auto_resolve_worker.py`
- [Deepgram](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/transcription-service/app/services/deepgram_client.py): speech client · Speech-to-text provider integration · `services/transcription-service/app/services/deepgram_client.py`
- [Transcription Data](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/transcription-service/app/models/transcription_job.py): transcription models · Jobs, transcripts, and utterances · `services/transcription-service/app/models/transcription_job.py`

### AI Analysis

Meeting insights and task extraction

- [Analysis API](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/ai-analysis-service/app/routers/analysis.py): analysis service · Summaries, tasks, and analysis jobs · `services/ai-analysis-service/app/routers/analysis.py`
- [Transcription Sub](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/ai-analysis-service/app/subscribers/transcription_subscriber.py): event subscriber · Consumes transcription output events · `services/ai-analysis-service/app/subscribers/transcription_subscriber.py`
- [Groq Analysis](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/ai-analysis-service/app/services/groq_service.py): llm service · LLM-backed summary and task generation · `services/ai-analysis-service/app/services/groq_service.py`
- [Analysis Data](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/ai-analysis-service/app/models/analysis_job.py): analysis models · Analysis jobs, summaries, and extracted tasks · `services/ai-analysis-service/app/models/analysis_job.py`

### AI Utils

Narrow AI helper service

- [AI API](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/ai-service/app/routers/upload.py): ai helper · Upload and summarize endpoints · `services/ai-service/app/routers/upload.py`
- [AI Models](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/ai-service/app/services/whisper_service.py): ai helper · AI utility service internals · `services/ai-service/app/services/whisper_service.py`

### Integrations

Calendar and Trello synchronization

- [Sync API](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/integration-service/app/routers/sync.py): integration service · Calendar and Trello sync endpoints · `services/integration-service/app/routers/sync.py`
- [Integration Worker](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/integration-service/app/workers/integration_worker.py): async worker · Runs sync reconciliation jobs · `services/integration-service/app/workers/integration_worker.py`
- [Sync Data](https://github.com/dothanhbao1805/meeting_assistant_be/blob/master/services/integration-service/app/models/sync_queue.py): integration models · Calendar events, sync queue, and sync logs · `services/integration-service/app/models/sync_queue.py`

### External Systems

Third-party and infrastructure dependencies

- **Redis**: infra cache · Shared async state and queues
- **Google Calendar**: external api · Calendar sync target
- **Trello**: external api · Task board sync target
- **Cloudinary**: media store · File and asset storage
- **Groq**: llm api · Summarization and extraction model provider
- **Whisper**: speech model · Audio transcription helper

## Connections

- API Gateway → Auth API: routes to · Gateway forwards auth traffic
- API Gateway → Company API: routes to · Gateway forwards workspace traffic
- API Gateway → Meeting API: routes to · Gateway forwards meeting traffic
- API Gateway → Transcribe API: routes to · Gateway forwards transcription traffic
- API Gateway → Analysis API: routes to · Gateway forwards analysis traffic
- Auth API → Auth Logic: uses · Auth routers call service logic
- Auth Logic → Users: persists · User and token persistence
- Company API → Member Voice: uses · Member endpoints rely on voice matching
- Member Voice → Company Data: persists · Workspace entities and settings
- Company API → Cloudinary: stores · Company assets and media storage
- Meeting API → Meeting Files: uses · Meeting file upload and retrieval
- Meeting Files → Meeting Data: persists · Meeting records and files
- Transcribe API → Deepgram: calls · Speech-to-text provider integration
- Transcribe API → Transcribe Worker: enqueues · Job processing continues asynchronously
- Transcribe Worker → Redis: uses · Background coordination and state
- Transcribe Worker → Transcription Data: updates · Job and transcript state changes
- Transcribe API → Transcription Data: persists · Transcription domain records
- Analysis API → Groq Analysis: uses · Generates summaries and tasks
- Analysis API → Transcription Sub: consumes · Receives transcription-driven events
- Transcription Sub → Groq: publishes to · Event-driven analysis execution
- Groq Analysis → Analysis Data: persists · Analysis jobs, summaries, and tasks
- AI API → AI Models: uses · Upload and summarize helper logic
- AI Models → Whisper: calls · Audio transcription helper
- AI Models → Groq: calls · Summarization helper
- Sync API → Integration Worker: queues · Sync tasks run asynchronously
- Integration Worker → Redis: uses · Queueing and coordination
- Sync API → Sync Data: persists · Sync queues, events, and logs
- Sync API → Google Calendar: syncs · Calendar synchronization boundary
- Sync API → Trello: syncs · Trello synchronization boundary
- Sync API → Company API: reads · Uses company data for sync decisions
