# nour-el-dandachi/gitmap architecture

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

- Interactive diagram: https://gitdiagram.com/nour-el-dandachi/gitmap
- Repository: https://github.com/nour-el-dandachi/gitmap

## Overview

GitMap is a web application for understanding and monitoring GitHub repositories. Users authenticate, add a repository, and receive a file map; they can also ask file-specific questions, view change notifications, and inspect defect-risk metrics. The sampled indexing service fetches and stores repository metadata, selects files for indexing, and queues embedding work. Several UI-to-API and unsampled feature connections are described only at the README level, so those edges cite the README; no unsampled implementation details are assumed.

Main entry points: [`frontend/src/routes/MyRoutes.jsx`](https://github.com/nour-el-dandachi/gitmap/blob/main/frontend/src/routes/MyRoutes.jsx) (Page routing), [`backend/repositories/services/repo_service.py`](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/services/repo_service.py) (Repository indexing), [`backend/repositories/models.py`](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/models.py) (Repository and file records), [`backend/chat/services/chat_service.py`](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/chat/services/chat_service.py) (File Q&A)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_routes["Page routing<br/>[MyRoutes.jsx]"]
  node_repo_ui["Repository screens<br/>[index.jsx]"]
  node_dashboard["Dashboard<br/>[index.jsx]"]
  node_map_ui["Interactive code map<br/>[index.jsx]"]
  node_notification_ui["Notification screens<br/>[index.jsx]"]
  node_auth_ui["Login and registration<br/>[index.jsx]"]
end

subgraph group_identity["Identity"]
  node_auth_routes["Authentication endpoints<br/>[auth_views.py]"]
  node_auth_service["Authentication service<br/>[auth_service.py]"]
  node_github_auth["GitHub OAuth"]
end

subgraph group_repos["Repository intelligence"]
  node_repository_api["Repository endpoints<br/>[repo_views.py]"]
  node_repo_service["Repository indexing<br/>[repo_service.py]"]
  node_embedding_task["Embedding task<br/>[tasks.py]"]
  node_embedding_service["Content embedding"]
  node_map_service["Map generation and layout<br/>[map_service.py]"]
  node_map_api["Map endpoints<br/>[map_views.py]"]
end

subgraph group_insights["Insights"]
  node_chat_service["File Q&amp;A<br/>[chat_service.py]"]
  node_metrics_task["Metrics extraction task<br/>[tasks.py]"]
  node_metrics_extractor["Code metrics extraction<br/>[extractor.py]"]
  node_ml_inference["Defect-risk prediction<br/>[inference.py]"]
  node_notification_service["Change notifications"]
end

subgraph group_platform["Backend data and jobs"]
  node_user_store[("User records<br/>[models.py]")]
  node_repo_store[("Repository and file records<br/>[models.py]")]
  node_map_store[("Map positions and edges<br/>[models.py]")]
  node_chat_store[("Chat sessions and messages<br/>[models.py]")]
  node_metrics_store[("File metrics<br/>[models.py]")]
  node_notification_store[("Notifications<br/>[models.py]")]
  node_celery["Background task runtime<br/>[celery.py]"]
end

node_user(("Repository user"))
node_github["GitHub API"]
node_openai["OpenAI API"]

node_user -->|"uses"| node_routes
node_routes -->|"routes to"| node_auth_ui
node_routes -->|"routes to"| node_dashboard
node_routes -->|"routes to"| node_repo_ui
node_routes -->|"routes to"| node_map_ui
node_routes -->|"routes to"| node_notification_ui
node_auth_ui -.->|"authenticates through"| node_auth_routes
node_auth_routes -->|"calls"| node_auth_service
node_auth_service -->|"creates user"| node_user_store
node_auth_service -.->|"supports OAuth"| node_github_auth
node_github_auth -->|"requests profile"| node_github
node_github_auth -->|"finds or creates"| node_user_store
node_repo_ui -.->|"manages repositories"| node_repository_api
node_repository_api -.->|"uses"| node_repo_service
node_repo_service -->|"fetches repository data"| node_github
node_repo_service -->|"stores repository files"| node_repo_store
node_repo_service -->|"queues embedding"| node_embedding_task
node_embedding_task -->|"runs"| node_embedding_service
node_embedding_service -->|"fetches file content"| node_repo_service
node_embedding_service -->|"stores chunks and vectors"| node_repo_store
node_map_ui -.->|"requests map data"| node_map_api
node_map_api -.->|"uses"| node_map_service
node_map_service -->|"reads and writes"| node_map_store
node_map_service -->|"loads repository files"| node_repo_store
node_user -.->|"asks file questions"| node_chat_service
node_chat_service -->|"records conversation"| node_chat_store
node_chat_service -->|"searches file chunks"| node_repo_store
node_chat_service -->|"requests answer"| node_openai
node_metrics_task -->|"extracts metrics"| node_metrics_extractor
node_metrics_task -->|"selects repository files"| node_repo_store
node_metrics_extractor -->|"persists metrics"| node_metrics_store
node_ml_inference -->|"uses file metrics"| node_metrics_store
node_user -->|"reviews changes"| node_notification_ui
node_notification_ui -.->|"loads notifications"| node_notification_service
node_notification_service -->|"manages notifications"| node_notification_store
node_celery -.->|"hosts task"| node_embedding_task
node_celery -.->|"hosts task"| node_metrics_task

click node_routes "https://github.com/nour-el-dandachi/gitmap/blob/main/frontend/src/routes/MyRoutes.jsx"
click node_repo_ui "https://github.com/nour-el-dandachi/gitmap/blob/main/frontend/src/pages/my-repositories/index.jsx"
click node_dashboard "https://github.com/nour-el-dandachi/gitmap/blob/main/frontend/src/pages/dashboard/index.jsx"
click node_map_ui "https://github.com/nour-el-dandachi/gitmap/blob/main/frontend/src/components/code-map/index.jsx"
click node_notification_ui "https://github.com/nour-el-dandachi/gitmap/blob/main/frontend/src/pages/notifications/index.jsx"
click node_auth_ui "https://github.com/nour-el-dandachi/gitmap/blob/main/frontend/src/pages/login/index.jsx"
click node_auth_routes "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/users/views/auth_views.py"
click node_auth_service "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/users/services/auth_service.py"
click node_github_auth "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/users/services/github_auth_service.py"
click node_user_store "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/users/models.py"
click node_repository_api "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/views/repo_views.py"
click node_repo_service "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/services/repo_service.py"
click node_repo_store "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/models.py"
click node_embedding_task "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/tasks.py"
click node_embedding_service "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/services/embedding_service.py"
click node_map_service "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/services/map_service.py"
click node_map_store "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/map/models.py"
click node_map_api "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/views/map_views.py"
click node_chat_service "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/chat/services/chat_service.py"
click node_chat_store "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/chat/models.py"
click node_metrics_task "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/metrics/tasks.py"
click node_metrics_extractor "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/metrics/services/extractor.py"
click node_metrics_store "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/metrics/models.py"
click node_ml_inference "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/ml_experiments/inference.py"
click node_notification_service "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/notifications/services/notification_service.py"
click node_notification_store "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/notifications/models.py"
click node_celery "https://github.com/nour-el-dandachi/gitmap/blob/main/backend/gitmap_backend/celery.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_routes,node_repo_ui,node_dashboard,node_map_ui,node_notification_ui,node_auth_ui,node_user toneBlue
class node_auth_routes,node_auth_service,node_github_auth toneAmber
class node_repository_api,node_repo_service,node_embedding_task,node_embedding_service,node_map_service,node_map_api,node_github,node_openai toneMint
class node_chat_service,node_metrics_task,node_metrics_extractor,node_ml_inference,node_notification_service toneRose
class node_user_store,node_repo_store,node_map_store,node_chat_store,node_metrics_store,node_notification_store,node_celery toneIndigo
```

## Components

### Web client

- [Page routing](https://github.com/nour-el-dandachi/gitmap/blob/main/frontend/src/routes/MyRoutes.jsx): `frontend/src/routes/MyRoutes.jsx`
- [Repository screens](https://github.com/nour-el-dandachi/gitmap/blob/main/frontend/src/pages/my-repositories/index.jsx): `frontend/src/pages/my-repositories/index.jsx`
- [Dashboard](https://github.com/nour-el-dandachi/gitmap/blob/main/frontend/src/pages/dashboard/index.jsx): `frontend/src/pages/dashboard/index.jsx`
- [Interactive code map](https://github.com/nour-el-dandachi/gitmap/blob/main/frontend/src/components/code-map/index.jsx): `frontend/src/components/code-map/index.jsx`
- [Notification screens](https://github.com/nour-el-dandachi/gitmap/blob/main/frontend/src/pages/notifications/index.jsx): `frontend/src/pages/notifications/index.jsx`
- [Login and registration](https://github.com/nour-el-dandachi/gitmap/blob/main/frontend/src/pages/login/index.jsx): `frontend/src/pages/login/index.jsx`

### Identity

- [Authentication endpoints](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/users/views/auth_views.py): `backend/users/views/auth_views.py`
- [Authentication service](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/users/services/auth_service.py): `backend/users/services/auth_service.py`
- [GitHub OAuth](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/users/services/github_auth_service.py): `backend/users/services/github_auth_service.py`

### Repository intelligence

- [Repository endpoints](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/views/repo_views.py): `backend/repositories/views/repo_views.py`
- [Repository indexing](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/services/repo_service.py): `backend/repositories/services/repo_service.py`
- [Embedding task](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/tasks.py): `backend/repositories/tasks.py`
- [Content embedding](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/services/embedding_service.py): `backend/repositories/services/embedding_service.py`
- [Map generation and layout](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/services/map_service.py): `backend/repositories/services/map_service.py`
- [Map endpoints](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/views/map_views.py): `backend/repositories/views/map_views.py`

### Insights

- [File Q&A](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/chat/services/chat_service.py): `backend/chat/services/chat_service.py`
- [Metrics extraction task](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/metrics/tasks.py): `backend/metrics/tasks.py`
- [Code metrics extraction](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/metrics/services/extractor.py): `backend/metrics/services/extractor.py`
- [Defect-risk prediction](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/ml_experiments/inference.py): `backend/ml_experiments/inference.py`
- [Change notifications](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/notifications/services/notification_service.py): `backend/notifications/services/notification_service.py`

### Backend data and jobs

- [User records](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/users/models.py): `backend/users/models.py`
- [Repository and file records](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/repositories/models.py): `backend/repositories/models.py`
- [Map positions and edges](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/map/models.py): `backend/map/models.py`
- [Chat sessions and messages](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/chat/models.py): `backend/chat/models.py`
- [File metrics](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/metrics/models.py): `backend/metrics/models.py`
- [Notifications](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/notifications/models.py): `backend/notifications/models.py`
- [Background task runtime](https://github.com/nour-el-dandachi/gitmap/blob/main/backend/gitmap_backend/celery.py): `backend/gitmap_backend/celery.py`

### Other components

- **Repository user**
- **GitHub API**
- **OpenAI API**

## Connections

- Repository user → Page routing: uses (evidence: `README.md`)
- Page routing → Login and registration: routes to (evidence: `frontend/src/routes/MyRoutes.jsx`)
- Page routing → Dashboard: routes to (evidence: `frontend/src/routes/MyRoutes.jsx`)
- Page routing → Repository screens: routes to (evidence: `frontend/src/routes/MyRoutes.jsx`)
- Page routing → Interactive code map: routes to (evidence: `frontend/src/routes/MyRoutes.jsx`)
- Page routing → Notification screens: routes to (evidence: `frontend/src/routes/MyRoutes.jsx`)
- Login and registration → Authentication endpoints: authenticates through (evidence: `README.md`)
- Authentication endpoints → Authentication service: calls (evidence: `backend/users/views/auth_views.py`)
- Authentication service → User records: creates user (evidence: `backend/users/services/auth_service.py`)
- Authentication service → GitHub OAuth: supports OAuth (evidence: `README.md`)
- GitHub OAuth → GitHub API: requests profile (evidence: `backend/users/services/github_auth_service.py`)
- GitHub OAuth → User records: finds or creates (evidence: `backend/users/services/github_auth_service.py`)
- Repository screens → Repository endpoints: manages repositories (evidence: `README.md`)
- Repository endpoints → Repository indexing: uses (evidence: `README.md`)
- Repository indexing → GitHub API: fetches repository data (evidence: `backend/repositories/services/repo_service.py`)
- Repository indexing → Repository and file records: stores repository files (evidence: `backend/repositories/services/repo_service.py`)
- Repository indexing → Embedding task: queues embedding (evidence: `backend/repositories/services/repo_service.py`)
- Embedding task → Content embedding: runs (evidence: `backend/repositories/tasks.py`)
- Content embedding → Repository indexing: fetches file content (evidence: `backend/repositories/services/embedding_service.py`)
- Content embedding → Repository and file records: stores chunks and vectors (evidence: `backend/repositories/services/embedding_service.py`)
- Interactive code map → Map endpoints: requests map data (evidence: `README.md`)
- Map endpoints → Map generation and layout: uses (evidence: `README.md`)
- Map generation and layout → Map positions and edges: reads and writes
- Map generation and layout → Repository and file records: loads repository files (evidence: `backend/repositories/services/map_service.py`)
- Repository user → File Q&A: asks file questions (evidence: `README.md`)
- File Q&A → Chat sessions and messages: records conversation (evidence: `backend/chat/services/chat_service.py`)
- File Q&A → Repository and file records: searches file chunks (evidence: `backend/chat/services/chat_service.py`)
- File Q&A → OpenAI API: requests answer (evidence: `backend/chat/services/chat_service.py`)
- Metrics extraction task → Code metrics extraction: extracts metrics (evidence: `backend/metrics/tasks.py`)
- Metrics extraction task → Repository and file records: selects repository files (evidence: `backend/metrics/tasks.py`)
- Code metrics extraction → File metrics: persists metrics (evidence: `backend/metrics/services/extractor.py`)
- Defect-risk prediction → File metrics: uses file metrics (evidence: `backend/ml_experiments/inference.py`)
- Repository user → Notification screens: reviews changes (evidence: `README.md`)
- Notification screens → Change notifications: loads notifications (evidence: `README.md`)
- Change notifications → Notifications: manages notifications (evidence: `backend/notifications/services/notification_service.py`)
- Background task runtime → Embedding task: hosts task (evidence: `backend/repositories/tasks.py`)
- Background task runtime → Metrics extraction task: hosts task (evidence: `backend/metrics/tasks.py`)