# arul-ananth/open-source-assist architecture

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

- Interactive diagram: https://gitdiagram.com/arul-ananth/open-source-assist
- Repository: https://github.com/arul-ananth/open-source-assist

## Overview

Open Source Assist is a repository-discovery and open-source learning platform. Users explore projects through semantic search and GitHub-backed discovery, then use learning, assessment, and roadmap features alongside community tools; accounts support personalized and administrative workflows. The README documents local embeddings, Qdrant retrieval, popularity-aware ranking, and extensible scoring. The source index confirms several route-to-service and service-to-service references, but many feature implementations were not excerpted; their nodes are retained from the repository tree and uncertain connections are omitted.

Main entry points: [`backend/main.py`](https://github.com/arul-ananth/open-source-assist/blob/main/backend/main.py) (API application), [`backend/services/search_service.py`](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/search_service.py) (Search orchestration), [`backend/services/embedding_service.py`](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/embedding_service.py) (Text embeddings), [`backend/services/auth_service.py`](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/auth_service.py) (Account workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Web application<br/>[App.tsx]"]
  node_dashboard["Dashboard<br/>[DashboardPage.tsx]"]
  node_roadmap_ui["Roadmap views<br/>[RoadmapPage.tsx]"]
  node_auth_ui["Authentication dialog<br/>[AuthDialog.tsx]"]
end

subgraph group_api["API workflows"]
  node_app_entry["API application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_search_routes["Search routes<br/>[search.py]"]
  node_github_routes["GitHub routes<br/>[github.py]"]
  node_learning_routes["Learning routes<br/>[learning.py]"]
  node_assessment_routes["Assessment routes<br/>[assessment.py]"]
  node_roadmap_routes["Roadmap routes<br/>[roadmaps.py]"]
  node_community_routes["Community routes<br/>[forum.py]"]
end

subgraph group_discovery["Repository discovery"]
  node_search_service["Search orchestration<br/>[search_service.py]"]
  node_embedding["Text embeddings"]
  node_vector_store[("Vector index<br/>[qdrant_service.py]")]
  node_ranking["Ranking strategy"]
  node_github_service["GitHub discovery<br/>[github_service.py]"]
  node_github_client["GitHub API client<br/>[github_client.py]"]
end

subgraph group_learning["Learning and community"]
  node_learning_service["Learning assistant<br/>[learning_agent.py]"]
  node_assessment_service["Skill assessment"]
  node_roadmap_service["Roadmap planning<br/>[roadmap_service.py]"]
  node_docs_service["Documentation explorer<br/>[doc_service.py]"]
  node_chat_service["Chatbot<br/>[chatbot_agent.py]"]
  node_forum_service["Forum service<br/>[forum_service.py]"]
end

subgraph group_platform["Platform services"]
  node_auth_service["Account workflows<br/>[auth_service.py]"]
  node_users[("User records<br/>[user_model.py]")]
  node_sql_database[("PostgreSQL sessions<br/>[database.py]")]
  node_configuration["Runtime configuration<br/>[config.py]"]
end

node_user(("User"))

node_user -.->|"uses"| node_frontend
node_frontend -.->|"calls API"| node_app_entry
node_app_entry -->|"registers"| node_auth_routes
node_app_entry -->|"registers"| node_search_routes
node_app_entry -->|"registers"| node_learning_routes
node_app_entry -->|"registers"| node_assessment_routes
node_app_entry -->|"registers"| node_roadmap_routes
node_app_entry -->|"registers"| node_community_routes
node_search_routes -->|"delegates to"| node_search_service
node_search_service -->|"embeds queries"| node_embedding
node_search_service -->|"retrieves vectors"| node_vector_store
node_search_service -->|"scores results"| node_ranking
node_search_service -->|"fetches candidates"| node_github_client
node_embedding -->|"loads settings"| node_configuration
node_embedding -->|"provides vectors"| node_vector_store
node_github_routes -->|"delegates to"| node_github_service
node_github_routes -->|"uses client"| node_github_client
node_auth_routes -->|"delegates to"| node_auth_service
node_auth_service -->|"reads and writes"| node_users
node_auth_service -.->|"uses session"| node_sql_database
node_assessment_routes -->|"delegates to"| node_assessment_service
node_roadmap_routes -->|"delegates to"| node_roadmap_service
node_community_routes -->|"delegates to"| node_forum_service
node_learning_routes -.->|"delegates to"| node_learning_service
node_app_entry -->|"checks collection"| node_vector_store
node_app_entry -->|"initializes"| node_sql_database

click node_frontend "https://github.com/arul-ananth/open-source-assist/blob/main/frontend/src/App.tsx"
click node_dashboard "https://github.com/arul-ananth/open-source-assist/blob/main/frontend/src/page/DashboardPage.tsx"
click node_roadmap_ui "https://github.com/arul-ananth/open-source-assist/blob/main/frontend/src/components/roadmap/RoadmapPage.tsx"
click node_auth_ui "https://github.com/arul-ananth/open-source-assist/blob/main/frontend/src/components/shared/AuthDialog.tsx"
click node_app_entry "https://github.com/arul-ananth/open-source-assist/blob/main/backend/main.py"
click node_auth_routes "https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/auth.py"
click node_search_routes "https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/routes/search.py"
click node_github_routes "https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/routes/github.py"
click node_learning_routes "https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/routes/learning.py"
click node_assessment_routes "https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/routes/assessment.py"
click node_roadmap_routes "https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/routes/roadmaps.py"
click node_community_routes "https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/routes/forum.py"
click node_search_service "https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/search_service.py"
click node_embedding "https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/embedding_service.py"
click node_vector_store "https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/qdrant_service.py"
click node_ranking "https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/scoring_strategy.py"
click node_github_service "https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/github_service.py"
click node_github_client "https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/github_client.py"
click node_learning_service "https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/learning_agent.py"
click node_assessment_service "https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/assessment_service.py"
click node_roadmap_service "https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/roadmap_service.py"
click node_docs_service "https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/doc_service.py"
click node_chat_service "https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/chatbot_agent.py"
click node_forum_service "https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/forum_service.py"
click node_auth_service "https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/auth_service.py"
click node_users "https://github.com/arul-ananth/open-source-assist/blob/main/backend/models/user_model.py"
click node_sql_database "https://github.com/arul-ananth/open-source-assist/blob/main/backend/core/database.py"
click node_configuration "https://github.com/arul-ananth/open-source-assist/blob/main/backend/core/config.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,node_dashboard,node_roadmap_ui,node_auth_ui,node_user toneBlue
class node_app_entry,node_auth_routes,node_search_routes,node_github_routes,node_learning_routes,node_assessment_routes,node_roadmap_routes,node_community_routes toneAmber
class node_search_service,node_embedding,node_vector_store,node_ranking,node_github_service,node_github_client toneMint
class node_learning_service,node_assessment_service,node_roadmap_service,node_docs_service,node_chat_service,node_forum_service toneRose
class node_auth_service,node_users,node_sql_database,node_configuration toneIndigo
```

## Components

### User experience

- [Web application](https://github.com/arul-ananth/open-source-assist/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard](https://github.com/arul-ananth/open-source-assist/blob/main/frontend/src/page/DashboardPage.tsx): `frontend/src/page/DashboardPage.tsx`
- [Roadmap views](https://github.com/arul-ananth/open-source-assist/blob/main/frontend/src/components/roadmap/RoadmapPage.tsx): `frontend/src/components/roadmap/RoadmapPage.tsx`
- [Authentication dialog](https://github.com/arul-ananth/open-source-assist/blob/main/frontend/src/components/shared/AuthDialog.tsx): `frontend/src/components/shared/AuthDialog.tsx`

### API workflows

- [API application](https://github.com/arul-ananth/open-source-assist/blob/main/backend/main.py): `backend/main.py`
- [Authentication routes](https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/auth.py): `backend/api/auth.py`
- [Search routes](https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/routes/search.py): `backend/api/routes/search.py`
- [GitHub routes](https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/routes/github.py): `backend/api/routes/github.py`
- [Learning routes](https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/routes/learning.py): `backend/api/routes/learning.py`
- [Assessment routes](https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/routes/assessment.py): `backend/api/routes/assessment.py`
- [Roadmap routes](https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/routes/roadmaps.py): `backend/api/routes/roadmaps.py`
- [Community routes](https://github.com/arul-ananth/open-source-assist/blob/main/backend/api/routes/forum.py): `backend/api/routes/forum.py`

### Repository discovery

- [Search orchestration](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/search_service.py): `backend/services/search_service.py`
- [Text embeddings](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/embedding_service.py): `backend/services/embedding_service.py`
- [Vector index](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/qdrant_service.py): `backend/services/qdrant_service.py`
- [Ranking strategy](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/scoring_strategy.py): `backend/services/scoring_strategy.py`
- [GitHub discovery](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/github_service.py): `backend/services/github_service.py`
- [GitHub API client](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/github_client.py): `backend/services/github_client.py`

### Learning and community

- [Learning assistant](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/learning_agent.py): `backend/services/learning_agent.py`
- [Skill assessment](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/assessment_service.py): `backend/services/assessment_service.py`
- [Roadmap planning](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/roadmap_service.py): `backend/services/roadmap_service.py`
- [Documentation explorer](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/doc_service.py): `backend/services/doc_service.py`
- [Chatbot](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/chatbot_agent.py): `backend/services/chatbot_agent.py`
- [Forum service](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/forum_service.py): `backend/services/forum_service.py`

### Platform services

- [Account workflows](https://github.com/arul-ananth/open-source-assist/blob/main/backend/services/auth_service.py): `backend/services/auth_service.py`
- [User records](https://github.com/arul-ananth/open-source-assist/blob/main/backend/models/user_model.py): `backend/models/user_model.py`
- [PostgreSQL sessions](https://github.com/arul-ananth/open-source-assist/blob/main/backend/core/database.py): `backend/core/database.py`
- [Runtime configuration](https://github.com/arul-ananth/open-source-assist/blob/main/backend/core/config.py): `backend/core/config.py`

### Other components

- **User**

## Connections

- User → Web application: uses
- Web application → API application: calls API
- API application → Authentication routes: registers (evidence: `backend/main.py`)
- API application → Search routes: registers (evidence: `backend/main.py`)
- API application → Learning routes: registers (evidence: `backend/main.py`)
- API application → Assessment routes: registers (evidence: `backend/main.py`)
- API application → Roadmap routes: registers (evidence: `backend/main.py`)
- API application → Community routes: registers (evidence: `backend/main.py`)
- Search routes → Search orchestration: delegates to (evidence: `backend/api/routes/search.py`)
- Search orchestration → Text embeddings: embeds queries (evidence: `backend/services/search_service.py`)
- Search orchestration → Vector index: retrieves vectors (evidence: `backend/services/search_service.py`)
- Search orchestration → Ranking strategy: scores results (evidence: `backend/services/search_service.py`)
- Search orchestration → GitHub API client: fetches candidates (evidence: `backend/services/search_service.py`)
- Text embeddings → Runtime configuration: loads settings (evidence: `backend/services/embedding_service.py`)
- Text embeddings → Vector index: provides vectors (evidence: `backend/services/qdrant_service.py`)
- GitHub routes → GitHub discovery: delegates to (evidence: `backend/api/routes/github.py`)
- GitHub routes → GitHub API client: uses client (evidence: `backend/api/routes/github.py`)
- Authentication routes → Account workflows: delegates to (evidence: `backend/api/auth.py`)
- Account workflows → User records: reads and writes (evidence: `backend/services/auth_service.py`)
- Account workflows → PostgreSQL sessions: uses session
- Assessment routes → Skill assessment: delegates to (evidence: `backend/api/routes/assessment.py`)
- Roadmap routes → Roadmap planning: delegates to (evidence: `backend/api/routes/roadmaps.py`)
- Community routes → Forum service: delegates to (evidence: `backend/api/routes/forum.py`)
- Learning routes → Learning assistant: delegates to
- API application → Vector index: checks collection (evidence: `backend/main.py`)
- API application → PostgreSQL sessions: initializes (evidence: `backend/main.py`)
