# mina-gerguis/qareeb architecture

> Architecture diagram of the GitHub repository mina-gerguis/qareeb, 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/mina-gerguis/qareeb
- Repository: https://github.com/mina-gerguis/qareeb

## Overview

Cairo Map is a Next.js application for discovering places and navigating transit in Egypt, with supporting community, account, editorial, and administrative features. The likely user journey is to choose a travel mode or destination, consult route or location information, and use related place details; the tree also shows dedicated airport, BRT, and AI-planner experiences. The graph preserves these major product areas, but excerpts do not establish most page-to-page calls or data flows, so those links are omitted rather than inferred. Admin management is represented as a subsystem because its detailed runtime wiring was not sampled.

Main entry points: [`src/context/AuthContext.tsx`](https://github.com/mina-gerguis/qareeb/blob/main/src/context/AuthContext.tsx) (Authentication), [`src/lib/supabase.ts`](https://github.com/mina-gerguis/qareeb/blob/main/src/lib/supabase.ts) (Supabase Client), [`src/components/common/RouteSearchCard/RouteSearchCard.tsx`](https://github.com/mina-gerguis/qareeb/blob/main/src/components/common/RouteSearchCard/RouteSearchCard.tsx) (Route Search), [`src/components/ReviewSection.tsx`](https://github.com/mina-gerguis/qareeb/blob/main/src/components/ReviewSection.tsx) (Place Reviews)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Place Discovery"]
  node_map_data["Map Experience<br/>[useMapData.ts]"]
  node_place_catalog["Place Catalog<br/>[places.ts]"]
  node_place_reviews["Place Reviews<br/>[ReviewSection.tsx]"]
  node_review_hook["Review Data Hook<br/>[usePlaceReviews.ts]"]
end

subgraph group_transit["Transit Navigation"]
  node_route_search["Route Search"]
  node_directions["Directions"]
  node_popular_routes["Popular Routes"]
  node_route_data["Route Data"]
  node_airports["Airport Guide<br/>[page.tsx]"]
  node_brt["BRT Guide<br/>[page.tsx]"]
end

subgraph group_accounts["Accounts And Community"]
  node_auth["Authentication<br/>[AuthContext.tsx]"]
  node_supabase[("Supabase Client<br/>[supabase.ts]")]
  node_notifications["Notifications"]
end

subgraph group_content["Content And Assistance"]
  node_blog_hook["Blog Browser<br/>[useBlogArticles.ts]"]
  node_ai_chat["AI Chat API<br/>[route.ts]"]
end

subgraph group_operations["Operations"]
  node_app_shell["Application Shell"]
  node_admin["Admin Console"]
end

node_traveler(("Traveler"))

node_traveler -.->|"chooses route"| node_route_search
node_route_search -.->|"submits search"| node_directions
node_directions -.->|"uses route data"| node_route_data
node_traveler -.->|"browses airports"| node_airports
node_traveler -.->|"browses BRT"| node_brt
node_traveler -.->|"explores map"| node_map_data
node_place_reviews -->|"reads user"| node_auth
node_place_reviews -->|"reads and writes reviews"| node_supabase
node_review_hook -->|"fetches reviews"| node_supabase
node_review_hook -->|"uses place type"| node_place_catalog
node_auth -->|"uses client"| node_supabase
node_auth -->|"provides session"| node_app_shell
node_app_shell -->|"reads account state"| node_auth
node_blog_hook -->|"reads user"| node_auth
node_blog_hook -->|"loads articles"| node_supabase
node_traveler -.->|"requests assistance"| node_ai_chat
node_route_search -.->|"accepts voice input"| node_traveler

click node_route_search "https://github.com/mina-gerguis/qareeb/blob/main/src/components/common/RouteSearchCard/RouteSearchCard.tsx"
click node_directions "https://github.com/mina-gerguis/qareeb/blob/main/src/app/directions/components/RouteSearchCard.tsx"
click node_popular_routes "https://github.com/mina-gerguis/qareeb/blob/main/src/app/directions/components/PopularRoutesSlider.tsx"
click node_route_data "https://github.com/mina-gerguis/qareeb/blob/main/src/data/directions_routes.ts"
click node_airports "https://github.com/mina-gerguis/qareeb/blob/main/src/app/airports/page.tsx"
click node_brt "https://github.com/mina-gerguis/qareeb/blob/main/src/app/brt/page.tsx"
click node_map_data "https://github.com/mina-gerguis/qareeb/blob/main/src/app/map/hooks/useMapData.ts"
click node_place_catalog "https://github.com/mina-gerguis/qareeb/blob/main/src/data/places.ts"
click node_place_reviews "https://github.com/mina-gerguis/qareeb/blob/main/src/components/ReviewSection.tsx"
click node_review_hook "https://github.com/mina-gerguis/qareeb/blob/main/src/app/places/%5Bid%5D/reviews/hooks/usePlaceReviews.ts"
click node_auth "https://github.com/mina-gerguis/qareeb/blob/main/src/context/AuthContext.tsx"
click node_supabase "https://github.com/mina-gerguis/qareeb/blob/main/src/lib/supabase.ts"
click node_notifications "https://github.com/mina-gerguis/qareeb/blob/main/src/context/NotificationContext.tsx"
click node_blog_hook "https://github.com/mina-gerguis/qareeb/blob/main/src/components/blog/useBlogArticles.ts"
click node_ai_chat "https://github.com/mina-gerguis/qareeb/blob/main/src/app/api/ai-chat/route.ts"
click node_app_shell "https://github.com/mina-gerguis/qareeb/blob/main/src/components/ClientLayoutWrapper.tsx"
click node_admin "https://github.com/mina-gerguis/qareeb/tree/main/src/app/admin"

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_map_data,node_place_catalog,node_place_reviews,node_review_hook toneBlue
class node_route_search,node_directions,node_popular_routes,node_route_data,node_airports,node_brt toneAmber
class node_auth,node_supabase,node_notifications toneMint
class node_blog_hook,node_ai_chat toneRose
class node_app_shell,node_admin,node_traveler toneIndigo
```

## Components

### Place Discovery

- [Map Experience](https://github.com/mina-gerguis/qareeb/blob/main/src/app/map/hooks/useMapData.ts): `src/app/map/hooks/useMapData.ts`
- [Place Catalog](https://github.com/mina-gerguis/qareeb/blob/main/src/data/places.ts): `src/data/places.ts`
- [Place Reviews](https://github.com/mina-gerguis/qareeb/blob/main/src/components/ReviewSection.tsx): `src/components/ReviewSection.tsx`
- [Review Data Hook](https://github.com/mina-gerguis/qareeb/blob/main/src/app/places/%5Bid%5D/reviews/hooks/usePlaceReviews.ts): `src/app/places/[id]/reviews/hooks/usePlaceReviews.ts`

### Transit Navigation

- [Route Search](https://github.com/mina-gerguis/qareeb/blob/main/src/components/common/RouteSearchCard/RouteSearchCard.tsx): `src/components/common/RouteSearchCard/RouteSearchCard.tsx`
- [Directions](https://github.com/mina-gerguis/qareeb/blob/main/src/app/directions/components/RouteSearchCard.tsx): `src/app/directions/components/RouteSearchCard.tsx`
- [Popular Routes](https://github.com/mina-gerguis/qareeb/blob/main/src/app/directions/components/PopularRoutesSlider.tsx): `src/app/directions/components/PopularRoutesSlider.tsx`
- [Route Data](https://github.com/mina-gerguis/qareeb/blob/main/src/data/directions_routes.ts): `src/data/directions_routes.ts`
- [Airport Guide](https://github.com/mina-gerguis/qareeb/blob/main/src/app/airports/page.tsx): `src/app/airports/page.tsx`
- [BRT Guide](https://github.com/mina-gerguis/qareeb/blob/main/src/app/brt/page.tsx): `src/app/brt/page.tsx`

### Accounts And Community

- [Authentication](https://github.com/mina-gerguis/qareeb/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`
- [Supabase Client](https://github.com/mina-gerguis/qareeb/blob/main/src/lib/supabase.ts): `src/lib/supabase.ts`
- [Notifications](https://github.com/mina-gerguis/qareeb/blob/main/src/context/NotificationContext.tsx): `src/context/NotificationContext.tsx`

### Content And Assistance

- [Blog Browser](https://github.com/mina-gerguis/qareeb/blob/main/src/components/blog/useBlogArticles.ts): `src/components/blog/useBlogArticles.ts`
- [AI Chat API](https://github.com/mina-gerguis/qareeb/blob/main/src/app/api/ai-chat/route.ts): `src/app/api/ai-chat/route.ts`

### Operations

- [Application Shell](https://github.com/mina-gerguis/qareeb/blob/main/src/components/ClientLayoutWrapper.tsx): `src/components/ClientLayoutWrapper.tsx`
- [Admin Console](https://github.com/mina-gerguis/qareeb/tree/main/src/app/admin): `src/app/admin`

### Other components

- **Traveler**

## Connections

- Traveler → Route Search: chooses route
- Route Search → Directions: submits search
- Directions → Route Data: uses route data
- Traveler → Airport Guide: browses airports
- Traveler → BRT Guide: browses BRT
- Traveler → Map Experience: explores map
- Place Reviews → Authentication: reads user (evidence: `src/components/ReviewSection.tsx`)
- Place Reviews → Supabase Client: reads and writes reviews (evidence: `src/components/ReviewSection.tsx`)
- Review Data Hook → Supabase Client: fetches reviews (evidence: `src/app/places/[id]/reviews/hooks/usePlaceReviews.ts`)
- Review Data Hook → Place Catalog: uses place type (evidence: `src/app/places/[id]/reviews/hooks/usePlaceReviews.ts`)
- Authentication → Supabase Client: uses client (evidence: `src/context/AuthContext.tsx`)
- Authentication → Application Shell: provides session (evidence: `src/components/ClientLayoutWrapper.tsx`)
- Application Shell → Authentication: reads account state (evidence: `src/components/ClientLayoutWrapper.tsx`)
- Blog Browser → Authentication: reads user (evidence: `src/components/blog/useBlogArticles.ts`)
- Blog Browser → Supabase Client: loads articles (evidence: `src/components/blog/useBlogArticles.ts`)
- Traveler → AI Chat API: requests assistance
- Route Search → Traveler: accepts voice input
