# dave0321/ecosync architecture

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

- Interactive diagram: https://gitdiagram.com/dave0321/ecosync
- Repository: https://github.com/dave0321/ecosync

## Overview

EcoSync orchestrates startup–mentor discovery: users register, startup and mentor profiles are represented semantically, and the documented AI pipeline combines graph, historical-context, and semantic signals into explainable recommendations. Organizers review pending matches and approve relationships; dashboards expose programme, ecosystem, analytics, and lifecycle views. Sampled backend routes confirm profile extraction and programme generation, but not match-generation routing. Other pipeline stages and frontend capabilities are documented in the README; their internal call wiring was not sampled.

Main entry points: [`ai_engine/main.py`](https://github.com/dave0321/ecosync/blob/main/ai_engine/main.py) (FastAPI engine), [`ai_engine/services/embeddings.py`](https://github.com/dave0321/ecosync/blob/main/ai_engine/services/embeddings.py) (Semantic embeddings), [`ai_engine/services`](https://github.com/dave0321/ecosync/tree/main/ai_engine/services) (Match lifecycle service), [`frontend/src/app/admin/dashboard/page.tsx`](https://github.com/dave0321/ecosync/blob/main/frontend/src/app/admin/dashboard/page.tsx) (Organizer console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Workspaces"]
  node_startup["Startup workspace<br/>[page.tsx]"]
  node_mentor["Mentor workspace<br/>[page.tsx]"]
  node_organizer["Organizer console<br/>[page.tsx]"]
end

subgraph group_identity["Identity and Data"]
  node_signup["Account signup<br/>[page.tsx]"]
  node_firebase_client["Firebase client<br/>[firebase.ts]"]
  node_supabase_client["Supabase client<br/>[supabase.ts]"]
  node_database_client["Backend database client<br/>[database.py]"]
  node_ecosystem_store[("Ecosystem store")]
end

subgraph group_engine["AI Matching Engine"]
  node_api["FastAPI engine<br/>[main.py]"]
  node_models["Profile and match models<br/>[models.py]"]
  node_extraction["Profile extraction<br/>[extraction.py]"]
  node_embeddings["Semantic embeddings<br/>[embeddings.py]"]
  node_graph_builder["Ecosystem graph"]
  node_hgt["HGT link prediction<br/>[hgt_model.py]"]
  node_rag["RAG retrieval"]
  node_ranker["Hybrid ranking"]
  node_explain["Match explanations"]
  node_programme_generator["Programme generation<br/>[generator.py]"]
end

subgraph group_lifecycle["Match Lifecycle"]
  node_lifecycle_service["Match lifecycle service"]
  node_recommendations[("Pending recommendations")]
  node_relationships[("Mentorship relationships")]
  node_feedback[("Outcome feedback")]
end

node_user(("Startup, mentor, organizer"))
node_firebase["Firebase Authentication"]
node_gemini["Google Gemini"]
node_supabase[("Supabase PostgreSQL")]

node_user -->|"registers"| node_signup
node_signup -->|"creates account"| node_firebase_client
node_signup -->|"registers profile"| node_supabase_client
node_firebase_client -.->|"authenticates"| node_firebase
node_supabase_client -.->|"accesses data"| node_supabase
node_user -.->|"uses"| node_startup
node_user -.->|"uses"| node_mentor
node_user -.->|"uses"| node_organizer
node_startup -.->|"requests matching"| node_api
node_mentor -.->|"requests matching"| node_api
node_organizer -.->|"uses REST API"| node_api
node_api -->|"checks health"| node_database_client
node_database_client -.->|"queries"| node_ecosystem_store
node_api -->|"extracts profile"| node_extraction
node_api -->|"generates details"| node_programme_generator
node_extraction -->|"extracts JSON"| node_gemini
node_programme_generator -->|"generates JSON"| node_gemini
node_extraction -.->|"feeds profiles"| node_embeddings
node_embeddings -.->|"stores vectors"| node_supabase
node_embeddings -.->|"provides vectors"| node_graph_builder
node_graph_builder -.->|"builds graph input"| node_hgt
node_embeddings -.->|"embeds knowledge"| node_rag
node_rag -.->|"retrieves context"| node_supabase
node_hgt -.->|"supplies graph score"| node_ranker
node_rag -.->|"supplies history"| node_ranker
node_embeddings -.->|"supplies semantic score"| node_ranker
node_ranker -.->|"selects top match"| node_explain
node_explain -.->|"generates narrative"| node_gemini
node_api -.->|"manages matches"| node_lifecycle_service
node_lifecycle_service -.->|"creates pending"| node_recommendations
node_lifecycle_service -.->|"activates approved"| node_relationships
node_lifecycle_service -.->|"records outcomes"| node_feedback
node_organizer -.->|"reviews pending"| node_recommendations

click node_startup "https://github.com/dave0321/ecosync/blob/main/frontend/src/app/startup/matches/page.tsx"
click node_mentor "https://github.com/dave0321/ecosync/blob/main/frontend/src/app/mentor/matches/page.tsx"
click node_organizer "https://github.com/dave0321/ecosync/blob/main/frontend/src/app/admin/dashboard/page.tsx"
click node_signup "https://github.com/dave0321/ecosync/blob/main/frontend/src/app/auth/signup/page.tsx"
click node_firebase_client "https://github.com/dave0321/ecosync/blob/main/frontend/src/lib/firebase.ts"
click node_supabase_client "https://github.com/dave0321/ecosync/blob/main/frontend/src/lib/supabase.ts"
click node_database_client "https://github.com/dave0321/ecosync/blob/main/ai_engine/database.py"
click node_api "https://github.com/dave0321/ecosync/blob/main/ai_engine/main.py"
click node_models "https://github.com/dave0321/ecosync/blob/main/ai_engine/models.py"
click node_extraction "https://github.com/dave0321/ecosync/blob/main/ai_engine/services/extraction.py"
click node_embeddings "https://github.com/dave0321/ecosync/blob/main/ai_engine/services/embeddings.py"
click node_graph_builder "https://github.com/dave0321/ecosync/tree/main/ai_engine/services"
click node_hgt "https://github.com/dave0321/ecosync/blob/main/ai_engine/services/hgt_model.py"
click node_rag "https://github.com/dave0321/ecosync/tree/main/ai_engine/services"
click node_ranker "https://github.com/dave0321/ecosync/tree/main/ai_engine/services"
click node_explain "https://github.com/dave0321/ecosync/tree/main/ai_engine/services"
click node_programme_generator "https://github.com/dave0321/ecosync/blob/main/ai_engine/services/generator.py"
click node_lifecycle_service "https://github.com/dave0321/ecosync/tree/main/ai_engine/services"

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_startup,node_mentor,node_organizer toneBlue
class node_signup,node_firebase_client,node_supabase_client,node_database_client,node_ecosystem_store,node_supabase toneAmber
class node_api,node_models,node_extraction,node_embeddings,node_graph_builder,node_hgt,node_rag,node_ranker,node_explain,node_programme_generator toneMint
class node_lifecycle_service,node_recommendations,node_relationships,node_feedback toneRose
class node_user,node_firebase,node_gemini toneIndigo
```

## Components

### User Workspaces

- [Startup workspace](https://github.com/dave0321/ecosync/blob/main/frontend/src/app/startup/matches/page.tsx): `frontend/src/app/startup/matches/page.tsx`
- [Mentor workspace](https://github.com/dave0321/ecosync/blob/main/frontend/src/app/mentor/matches/page.tsx): `frontend/src/app/mentor/matches/page.tsx`
- [Organizer console](https://github.com/dave0321/ecosync/blob/main/frontend/src/app/admin/dashboard/page.tsx): `frontend/src/app/admin/dashboard/page.tsx`

### Identity and Data

- [Account signup](https://github.com/dave0321/ecosync/blob/main/frontend/src/app/auth/signup/page.tsx): `frontend/src/app/auth/signup/page.tsx`
- [Firebase client](https://github.com/dave0321/ecosync/blob/main/frontend/src/lib/firebase.ts): `frontend/src/lib/firebase.ts`
- [Supabase client](https://github.com/dave0321/ecosync/blob/main/frontend/src/lib/supabase.ts): `frontend/src/lib/supabase.ts`
- [Backend database client](https://github.com/dave0321/ecosync/blob/main/ai_engine/database.py): `ai_engine/database.py`
- **Ecosystem store**

### AI Matching Engine

- [FastAPI engine](https://github.com/dave0321/ecosync/blob/main/ai_engine/main.py): `ai_engine/main.py`
- [Profile and match models](https://github.com/dave0321/ecosync/blob/main/ai_engine/models.py): `ai_engine/models.py`
- [Profile extraction](https://github.com/dave0321/ecosync/blob/main/ai_engine/services/extraction.py): `ai_engine/services/extraction.py`
- [Semantic embeddings](https://github.com/dave0321/ecosync/blob/main/ai_engine/services/embeddings.py): `ai_engine/services/embeddings.py`
- [Ecosystem graph](https://github.com/dave0321/ecosync/tree/main/ai_engine/services): `ai_engine/services`
- [HGT link prediction](https://github.com/dave0321/ecosync/blob/main/ai_engine/services/hgt_model.py): `ai_engine/services/hgt_model.py`
- [RAG retrieval](https://github.com/dave0321/ecosync/tree/main/ai_engine/services): `ai_engine/services`
- [Hybrid ranking](https://github.com/dave0321/ecosync/tree/main/ai_engine/services): `ai_engine/services`
- [Match explanations](https://github.com/dave0321/ecosync/tree/main/ai_engine/services): `ai_engine/services`
- [Programme generation](https://github.com/dave0321/ecosync/blob/main/ai_engine/services/generator.py): `ai_engine/services/generator.py`

### Match Lifecycle

- [Match lifecycle service](https://github.com/dave0321/ecosync/tree/main/ai_engine/services): `ai_engine/services`
- **Pending recommendations**
- **Mentorship relationships**
- **Outcome feedback**

### Other components

- **Startup, mentor, organizer**
- **Firebase Authentication**
- **Google Gemini**
- **Supabase PostgreSQL**

## Connections

- Startup, mentor, organizer → Account signup: registers (evidence: `frontend/src/app/auth/signup/page.tsx`)
- Account signup → Firebase client: creates account (evidence: `frontend/src/app/auth/signup/page.tsx`)
- Account signup → Supabase client: registers profile (evidence: `frontend/src/app/auth/signup/page.tsx`)
- Firebase client → Firebase Authentication: authenticates
- Supabase client → Supabase PostgreSQL: accesses data
- Startup, mentor, organizer → Startup workspace: uses
- Startup, mentor, organizer → Mentor workspace: uses
- Startup, mentor, organizer → Organizer console: uses
- Startup workspace → FastAPI engine: requests matching
- Mentor workspace → FastAPI engine: requests matching
- Organizer console → FastAPI engine: uses REST API
- FastAPI engine → Backend database client: checks health (evidence: `ai_engine/main.py`)
- Backend database client → Ecosystem store: queries
- FastAPI engine → Profile extraction: extracts profile (evidence: `ai_engine/main.py`)
- FastAPI engine → Programme generation: generates details (evidence: `ai_engine/main.py`)
- Profile extraction → Google Gemini: extracts JSON (evidence: `ai_engine/services/extraction.py`)
- Programme generation → Google Gemini: generates JSON (evidence: `ai_engine/services/generator.py`)
- Profile extraction → Semantic embeddings: feeds profiles
- Semantic embeddings → Supabase PostgreSQL: stores vectors
- Semantic embeddings → Ecosystem graph: provides vectors
- Ecosystem graph → HGT link prediction: builds graph input
- Semantic embeddings → RAG retrieval: embeds knowledge
- RAG retrieval → Supabase PostgreSQL: retrieves context
- HGT link prediction → Hybrid ranking: supplies graph score
- RAG retrieval → Hybrid ranking: supplies history
- Semantic embeddings → Hybrid ranking: supplies semantic score
- Hybrid ranking → Match explanations: selects top match
- Match explanations → Google Gemini: generates narrative
- FastAPI engine → Match lifecycle service: manages matches (evidence: `ai_engine/main.py`)
- Match lifecycle service → Pending recommendations: creates pending
- Match lifecycle service → Mentorship relationships: activates approved
- Match lifecycle service → Outcome feedback: records outcomes
- Organizer console → Pending recommendations: reviews pending
