# ahmedkhaleel2004/deepend-hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedkhaleel2004/deepend-hackathon
- Repository: https://github.com/ahmedkhaleel2004/deepend-hackathon

## Overview

DeepEnd turns a learner’s goals and experience into project recommendations, then generates actionable project timelines with code examples and progress tracking. The main flow is sign-in, survey, recommendation generation, project selection, timeline generation, and progress review. Firebase supports authentication and persisted user, project, and timeline data. The README also describes personalized recommendations and detailed markdown/code timelines; some implementation files were not excerpted, so those links are included only where the source index or documentation supports them.

Main entry points: [`lib/firebase.ts`](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/firebase.ts) (Firebase services), [`components/component/survey/survey-questions.tsx`](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/components/component/survey/survey-questions.tsx) (Survey experience), [`app/main/page.tsx`](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/app/main/page.tsx) (Learning workspace), [`lib/sign-in-or-create.ts`](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/sign-in-or-create.ts) (OAuth account flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and onboarding"]
  node_landing["Landing and sign-in<br/>[page.tsx]"]
  node_authflow["OAuth account flow"]
  node_authstate["Auth state<br/>[use-auth.ts]"]
  node_survey["Survey experience"]
  node_surveyanswers["Survey answer review<br/>[thanks-survey.tsx]"]
end

subgraph group_projects["Project discovery"]
  node_recommend["Project recommendations<br/>[route.ts]"]
  node_projectfetch["Project loading"]
  node_projectlist["Project selection<br/>[projects-list.tsx]"]
end

subgraph group_learning["Timelines and progress"]
  node_main["Learning workspace<br/>[page.tsx]"]
  node_timelinecreate["Timeline generation API<br/>[route.ts]"]
  node_timelinegen["Timeline generator"]
  node_timelineview["Timeline viewer<br/>[timeline.tsx]"]
  node_timelinecards["Step and code views<br/>[CardTimeline.tsx]"]
  node_timelinefetch["Timeline loading"]
end

subgraph group_platform["Persistence and services"]
  node_firebase[("Firebase services<br/>[firebase.ts]")]
  node_userdata["User profile lookup<br/>[get-user-data.ts]"]
  node_questions["Survey definitions<br/>[questions.ts]"]
end

node_learner(("Learner"))

node_learner -->|"starts at"| node_landing
node_landing -->|"opens sign-in"| node_authflow
node_authflow -->|"authenticates and writes"| node_firebase
node_authflow -->|"checks profile"| node_userdata
node_authstate -->|"observes auth"| node_firebase
node_authstate -->|"loads profile"| node_userdata
node_learner -->|"answers"| node_survey
node_survey -->|"uses prompts"| node_questions
node_survey -->|"stores answers"| node_firebase
node_survey -->|"requests projects"| node_recommend
node_surveyanswers -->|"reads answers"| node_firebase
node_surveyanswers -->|"labels answers"| node_questions
node_recommend -->|"uses Firebase"| node_firebase
node_main -->|"checks access"| node_authstate
node_main -->|"shows projects"| node_projectlist
node_main -->|"shows timelines"| node_timelineview
node_projectlist -->|"loads projects"| node_projectfetch
node_projectfetch -->|"reads projects"| node_firebase
node_projectlist -->|"posts selection"| node_timelinecreate
node_timelinecreate -->|"dispatches generation"| node_timelinegen
node_timelinegen -->|"persists timeline"| node_firebase
node_timelineview -->|"loads timeline data"| node_timelinefetch
node_timelinefetch -->|"reads timelines"| node_firebase
node_timelineview -->|"renders steps"| node_timelinecards

click node_landing "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/app/page.tsx"
click node_authflow "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/sign-in-or-create.ts"
click node_authstate "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/hooks/use-auth.ts"
click node_survey "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/components/component/survey/survey-questions.tsx"
click node_surveyanswers "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/components/component/survey/thanks-survey.tsx"
click node_recommend "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/app/api/projects/route.ts"
click node_projectfetch "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/hooks/use-fetch-projects.ts"
click node_projectlist "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/components/component/sidebar/projects-list.tsx"
click node_main "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/app/main/page.tsx"
click node_timelinecreate "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/app/api/generate-timeline/route.ts"
click node_timelinegen "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/generate-timeline.ts"
click node_timelineview "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/components/component/timeline/timeline.tsx"
click node_timelinecards "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/components/component/Main/CardTimeline.tsx"
click node_timelinefetch "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/hooks/use-fetch-timelines.ts"
click node_firebase "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/firebase.ts"
click node_userdata "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/get-user-data.ts"
click node_questions "https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/questions.ts"

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_landing,node_authflow,node_authstate,node_survey,node_surveyanswers toneBlue
class node_recommend,node_projectfetch,node_projectlist toneAmber
class node_main,node_timelinecreate,node_timelinegen,node_timelineview,node_timelinecards,node_timelinefetch toneMint
class node_firebase,node_userdata,node_questions toneRose
class node_learner toneIndigo
```

## Components

### Identity and onboarding

- [Landing and sign-in](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/app/page.tsx): `app/page.tsx`
- [OAuth account flow](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/sign-in-or-create.ts): `lib/sign-in-or-create.ts`
- [Auth state](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/hooks/use-auth.ts): `lib/hooks/use-auth.ts`
- [Survey experience](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/components/component/survey/survey-questions.tsx): `components/component/survey/survey-questions.tsx`
- [Survey answer review](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/components/component/survey/thanks-survey.tsx): `components/component/survey/thanks-survey.tsx`

### Project discovery

- [Project recommendations](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/app/api/projects/route.ts): `app/api/projects/route.ts`
- [Project loading](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/hooks/use-fetch-projects.ts): `lib/hooks/use-fetch-projects.ts`
- [Project selection](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/components/component/sidebar/projects-list.tsx): `components/component/sidebar/projects-list.tsx`

### Timelines and progress

- [Learning workspace](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/app/main/page.tsx): `app/main/page.tsx`
- [Timeline generation API](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/app/api/generate-timeline/route.ts): `app/api/generate-timeline/route.ts`
- [Timeline generator](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/generate-timeline.ts): `lib/generate-timeline.ts`
- [Timeline viewer](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/components/component/timeline/timeline.tsx): `components/component/timeline/timeline.tsx`
- [Step and code views](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/components/component/Main/CardTimeline.tsx): `components/component/Main/CardTimeline.tsx`
- [Timeline loading](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/hooks/use-fetch-timelines.ts): `lib/hooks/use-fetch-timelines.ts`

### Persistence and services

- [Firebase services](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/firebase.ts): `lib/firebase.ts`
- [User profile lookup](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/get-user-data.ts): `lib/get-user-data.ts`
- [Survey definitions](https://github.com/ahmedkhaleel2004/deepend-hackathon/blob/main/lib/questions.ts): `lib/questions.ts`

### Other components

- **Learner**

## Connections

- Learner → Landing and sign-in: starts at (evidence: `app/page.tsx`)
- Landing and sign-in → OAuth account flow: opens sign-in
- OAuth account flow → Firebase services: authenticates and writes (evidence: `lib/sign-in-or-create.ts`)
- OAuth account flow → User profile lookup: checks profile (evidence: `lib/sign-in-or-create.ts`)
- Auth state → Firebase services: observes auth (evidence: `lib/hooks/use-auth.ts`)
- Auth state → User profile lookup: loads profile (evidence: `lib/hooks/use-auth.ts`)
- Learner → Survey experience: answers
- Survey experience → Survey definitions: uses prompts (evidence: `components/component/survey/survey-questions.tsx`)
- Survey experience → Firebase services: stores answers (evidence: `components/component/survey/survey-questions.tsx`)
- Survey experience → Project recommendations: requests projects
- Survey answer review → Firebase services: reads answers (evidence: `components/component/survey/thanks-survey.tsx`)
- Survey answer review → Survey definitions: labels answers (evidence: `components/component/survey/thanks-survey.tsx`)
- Project recommendations → Firebase services: uses Firebase (evidence: `app/api/projects/route.ts`)
- Learning workspace → Auth state: checks access (evidence: `app/main/page.tsx`)
- Learning workspace → Project selection: shows projects (evidence: `app/main/page.tsx`)
- Learning workspace → Timeline viewer: shows timelines (evidence: `app/main/page.tsx`)
- Project selection → Project loading: loads projects (evidence: `components/component/sidebar/projects-list.tsx`)
- Project loading → Firebase services: reads projects (evidence: `lib/hooks/use-fetch-projects.ts`)
- Project selection → Timeline generation API: posts selection (evidence: `components/component/sidebar/projects-list.tsx`)
- Timeline generation API → Timeline generator: dispatches generation (evidence: `app/api/generate-timeline/route.ts`)
- Timeline generator → Firebase services: persists timeline (evidence: `lib/generate-timeline.ts`)
- Timeline viewer → Timeline loading: loads timeline data (evidence: `components/component/timeline/timeline.tsx`)
- Timeline loading → Firebase services: reads timelines (evidence: `lib/hooks/use-fetch-timelines.ts`)
- Timeline viewer → Step and code views: renders steps (evidence: `components/component/timeline/timeline.tsx`)
