# modamaan/hackathon architecture

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

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

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** application written in **TypeScript**. The repo is organized as a single full-stack web app with UI, client-side interactive components, and server-side API routes in the same codebase.

2. **Primary user-facing routes**
   - `app/page.tsx` is the landing page.
   - `app/diagnose/page.tsx` is the main workflow page.
   - `app/history/page.tsx` shows prior activity or past diagnoses.
   - `app/layout.tsx` and `app/globals.css` define the shared shell, styling, and top-level composition for all pages.

3. **Core workflow boundary**
   - The application center of gravity appears to be the **diagnosis flow**: users provide inputs, the app processes them through API endpoints, and results are displayed back in the client.
   - The main client-side orchestration lives in `components/diagnose-client.tsx`, which likely coordinates input capture, submission, and rendering of results.

4. **Input capture subsystem**
   - `components/voice-recorder.tsx` handles audio capture.
   - `components/leaf-uploader.tsx` handles image/file input.
   - `components/location-picker.tsx` handles location selection.
   - Together these suggest the diagnosis request can combine **voice, image, and location context** before sending to the backend.

5. **Server API layer**
   - `app/api/transcribe/route.ts` is the audio-processing entry point, likely converting recorded speech into text.
   - `app/api/analyze/route.ts` is the main inference/analysis endpoint that consumes user-provided inputs and returns diagnosis output.
   - `app/api/history/route.ts` exposes history data for the history page and probably for persistence/readback of previous sessions.

6. **Data flow through the system**
   - The client gathers inputs through specialized components.
   - Audio is sent to `/api/transcribe` for transcription.
   - The resulting text, along with other inputs such as uploaded leaf data and location, is sent to `/api/analyze`.
   - Results are rendered in `components/results-panel.tsx`.
   - Historical records are retrieved through `/api/history` and shown in the history page.

7. **State, auth, and backend boundary**
   - `components/auth-provider.tsx` indicates authentication state is managed on the client side and shared across the app.
   - `lib/firebase.ts` and `lib/firebase-admin.ts` show a split between **client Firebase usage** and **server-side admin access**.
   - This usually means authenticated client interactions are paired with privileged server operations for reading/writing protected data.

8. **Likely persistence and external services**
   - The presence of Firebase client/admin libraries strongly suggests Firebase is the main external platform for authentication and/or data storage.
   - The `history` endpoint and auth provider imply user-scoped records are persisted and later queried, with server-admin code handling trusted access.

9. **Shared UI component layer**
   - `components/ui/*` contains reusable presentational primitives such as buttons, cards, tabs, badges, progress, skeletons, and sonner/toast UI.
   - These are likely a design-system layer used across the landing, diagnosis, and history pages to keep styling consistent.

10. **Page composition and navigation**
   - `components/navbar.tsx` provides cross-page navigation and likely user/session-aware controls.
   - `app/diagnose/page.tsx` and `app/history/page.tsx` are thin page shells that assemble the reusable client components rather than containing most business logic themselves.

11. **Shared utilities and types**
   - `lib/types.ts` defines domain shapes used across client and server boundaries.
   - `lib/utils.ts` and `lib/button-variants.ts` support shared formatting, class handling, and component styling concerns.
   - These files reduce duplication between route handlers and React components.

12. **Implementation constraints that matter architecturally**
   - The repo is designed around the **App Router split**: server route handlers under `app/api` and client interactions under `components`.
   - Because there are separate Firebase client/admin modules, the architecture likely enforces a trust boundary between browser code and privileged server code.
   - Styling and UI are centralized, but the business flow is concentrated in the diagnosis pipeline and history retrieval.

Main entry points: [`components/diagnose-client.tsx`](https://github.com/modamaan/hackathon/blob/main/components/diagnose-client.tsx) (Diagnose Client), [`app/layout.tsx`](https://github.com/modamaan/hackathon/blob/main/app/layout.tsx) (App Shell), [`app/history/page.tsx`](https://github.com/modamaan/hackathon/blob/main/app/history/page.tsx) (History Page), [`app/api/analyze/route.ts`](https://github.com/modamaan/hackathon/blob/main/app/api/analyze/route.ts) (Analyze API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["App Router"]
  node_n_home["Landing<br/>page<br/>[page.tsx]"]
  node_n_diag_page["Diagnose Page<br/>[page.tsx]"]
  node_n_hist_page["History Page<br/>[page.tsx]"]
  node_n_layout["App Shell<br/>layout<br/>[layout.tsx]"]
  node_n_styles["Global Styles<br/>[globals.css]"]
  node_n_api_transcribe["Transcribe API<br/>route<br/>[route.ts]"]
  node_n_api_analyze["Analyze API<br/>route<br/>[route.ts]"]
  node_n_api_history["History API<br/>route<br/>[route.ts]"]
end

subgraph group_grp_client["Client Flow"]
  node_n_navbar["Navbar<br/>navigation<br/>[navbar.tsx]"]
  node_n_auth["Auth Provider<br/>client auth<br/>[auth-provider.tsx]"]
  node_n_diag_client["Diagnose Client<br/>orchestrator"]
  node_n_voice["Voice Recorder<br/>input capture<br/>[voice-recorder.tsx]"]
  node_n_leaf["Leaf Uploader<br/>input capture<br/>[leaf-uploader.tsx]"]
  node_n_location["Location Picker<br/>input capture"]
  node_n_results["Results Panel<br/>output view<br/>[results-panel.tsx]"]
end

subgraph group_grp_ui["UI Primitives"]
  node_n_ui["UI Primitives<br/>design system"]
end

subgraph group_grp_lib["Shared Lib"]
  node_n_firebase["Firebase Client<br/>client sdk<br/>[firebase.ts]"]
  node_n_firebase_admin["Firebase Admin<br/>server sdk<br/>[firebase-admin.ts]"]
  node_n_types["Shared Types<br/>[types.ts]"]
  node_n_utils["Utils<br/>helpers<br/>[utils.ts]"]
  node_n_button_variants["Button Variants<br/>styling helpers<br/>[button-variants.ts]"]
end

node_n_home -->|"wrapped by"| node_n_layout
node_n_diag_page -->|"wrapped by"| node_n_layout
node_n_hist_page -->|"wrapped by"| node_n_layout
node_n_layout -->|"includes"| node_n_navbar
node_n_layout -->|"provides"| node_n_auth
node_n_layout -->|"applies"| node_n_styles
node_n_navbar -->|"uses"| node_n_ui
node_n_diag_page -->|"mounts"| node_n_diag_client
node_n_hist_page -->|"loads"| node_n_api_history
node_n_diag_client -->|"captures"| node_n_voice
node_n_diag_client -->|"captures"| node_n_leaf
node_n_diag_client -->|"captures"| node_n_location
node_n_diag_client -->|"calls"| node_n_api_transcribe
node_n_diag_client -->|"calls"| node_n_api_analyze
node_n_diag_client -->|"renders"| node_n_results
node_n_api_transcribe -->|"may use"| node_n_firebase_admin
node_n_api_analyze -->|"may use"| node_n_firebase_admin
node_n_api_history -->|"uses"| node_n_firebase_admin
node_n_auth -->|"uses"| node_n_firebase
node_n_api_history -->|"shares"| node_n_types
node_n_api_analyze -->|"shares"| node_n_types
node_n_diag_client -->|"uses"| node_n_types
node_n_ui -->|"supported by"| node_n_utils
node_n_ui -->|"uses"| node_n_button_variants
node_n_results -->|"uses"| node_n_ui
node_n_diag_client -->|"uses"| node_n_ui
node_n_home -->|"uses"| node_n_ui
node_n_hist_page -->|"uses"| node_n_ui

click node_n_home "https://github.com/modamaan/hackathon/blob/main/app/page.tsx"
click node_n_diag_page "https://github.com/modamaan/hackathon/blob/main/app/diagnose/page.tsx"
click node_n_hist_page "https://github.com/modamaan/hackathon/blob/main/app/history/page.tsx"
click node_n_layout "https://github.com/modamaan/hackathon/blob/main/app/layout.tsx"
click node_n_styles "https://github.com/modamaan/hackathon/blob/main/app/globals.css"
click node_n_api_transcribe "https://github.com/modamaan/hackathon/blob/main/app/api/transcribe/route.ts"
click node_n_api_analyze "https://github.com/modamaan/hackathon/blob/main/app/api/analyze/route.ts"
click node_n_api_history "https://github.com/modamaan/hackathon/blob/main/app/api/history/route.ts"
click node_n_navbar "https://github.com/modamaan/hackathon/blob/main/components/navbar.tsx"
click node_n_auth "https://github.com/modamaan/hackathon/blob/main/components/auth-provider.tsx"
click node_n_diag_client "https://github.com/modamaan/hackathon/blob/main/components/diagnose-client.tsx"
click node_n_voice "https://github.com/modamaan/hackathon/blob/main/components/voice-recorder.tsx"
click node_n_leaf "https://github.com/modamaan/hackathon/blob/main/components/leaf-uploader.tsx"
click node_n_location "https://github.com/modamaan/hackathon/blob/main/components/location-picker.tsx"
click node_n_results "https://github.com/modamaan/hackathon/blob/main/components/results-panel.tsx"
click node_n_firebase "https://github.com/modamaan/hackathon/blob/main/lib/firebase.ts"
click node_n_firebase_admin "https://github.com/modamaan/hackathon/blob/main/lib/firebase-admin.ts"
click node_n_types "https://github.com/modamaan/hackathon/blob/main/lib/types.ts"
click node_n_utils "https://github.com/modamaan/hackathon/blob/main/lib/utils.ts"
click node_n_button_variants "https://github.com/modamaan/hackathon/blob/main/lib/button-variants.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_n_home,node_n_diag_page,node_n_hist_page,node_n_layout,node_n_styles,node_n_api_transcribe,node_n_api_analyze,node_n_api_history toneBlue
class node_n_navbar,node_n_auth,node_n_diag_client,node_n_voice,node_n_leaf,node_n_location,node_n_results toneAmber
class node_n_ui toneMint
class node_n_firebase,node_n_firebase_admin,node_n_types,node_n_utils,node_n_button_variants toneRose
```

## Components

### App Router

Pages and server API routes

- [Landing](https://github.com/modamaan/hackathon/blob/main/app/page.tsx): page · Entry page for the app · `app/page.tsx`
- [Diagnose Page](https://github.com/modamaan/hackathon/blob/main/app/diagnose/page.tsx): page · Main workflow page shell · `app/diagnose/page.tsx`
- [History Page](https://github.com/modamaan/hackathon/blob/main/app/history/page.tsx): page · Past activity and diagnoses · `app/history/page.tsx`
- [App Shell](https://github.com/modamaan/hackathon/blob/main/app/layout.tsx): layout · Shared top-level layout · `app/layout.tsx`
- [Global Styles](https://github.com/modamaan/hackathon/blob/main/app/globals.css): styles · App-wide CSS · `app/globals.css`
- [Transcribe API](https://github.com/modamaan/hackathon/blob/main/app/api/transcribe/route.ts): route · Speech-to-text entry point · `app/api/transcribe/route.ts`
- [Analyze API](https://github.com/modamaan/hackathon/blob/main/app/api/analyze/route.ts): route · Main diagnosis inference endpoint · `app/api/analyze/route.ts`
- [History API](https://github.com/modamaan/hackathon/blob/main/app/api/history/route.ts): route · Fetches stored diagnosis history · `app/api/history/route.ts`

### Client Flow

Interactive diagnosis UI and page composition

- [Navbar](https://github.com/modamaan/hackathon/blob/main/components/navbar.tsx): navigation · Cross-page navigation and session-aware chrome · `components/navbar.tsx`
- [Auth Provider](https://github.com/modamaan/hackathon/blob/main/components/auth-provider.tsx): client auth · Shared authentication state · `components/auth-provider.tsx`
- [Diagnose Client](https://github.com/modamaan/hackathon/blob/main/components/diagnose-client.tsx): orchestrator · Coordinates input capture and analysis flow · `components/diagnose-client.tsx`
- [Voice Recorder](https://github.com/modamaan/hackathon/blob/main/components/voice-recorder.tsx): input capture · Audio capture and recording · `components/voice-recorder.tsx`
- [Leaf Uploader](https://github.com/modamaan/hackathon/blob/main/components/leaf-uploader.tsx): input capture · Image or file upload input · `components/leaf-uploader.tsx`
- [Location Picker](https://github.com/modamaan/hackathon/blob/main/components/location-picker.tsx): input capture · Location/context selection · `components/location-picker.tsx`
- [Results Panel](https://github.com/modamaan/hackathon/blob/main/components/results-panel.tsx): output view · Renders analysis results · `components/results-panel.tsx`

### UI Primitives

Reusable presentation components

- **UI Primitives**: design system · Reusable component set

### Shared Lib

Cross-cutting utilities and Firebase boundary

- [Firebase Client](https://github.com/modamaan/hackathon/blob/main/lib/firebase.ts): client sdk · Browser-side Firebase access · `lib/firebase.ts`
- [Firebase Admin](https://github.com/modamaan/hackathon/blob/main/lib/firebase-admin.ts): server sdk · Privileged server-side Firebase access · `lib/firebase-admin.ts`
- [Shared Types](https://github.com/modamaan/hackathon/blob/main/lib/types.ts): types · Domain shapes used across client and server · `lib/types.ts`
- [Utils](https://github.com/modamaan/hackathon/blob/main/lib/utils.ts): helpers · Shared utility helpers · `lib/utils.ts`
- [Button Variants](https://github.com/modamaan/hackathon/blob/main/lib/button-variants.ts): styling helpers · Variant definitions for buttons · `lib/button-variants.ts`

## Connections

- Landing → App Shell: wrapped by · Landing page uses shared shell
- Diagnose Page → App Shell: wrapped by · Diagnose page uses shared shell
- History Page → App Shell: wrapped by · History page uses shared shell
- App Shell → Navbar: includes · Global navigation chrome
- App Shell → Auth Provider: provides · Shares session state across pages
- App Shell → Global Styles: applies · Global styling foundation
- Navbar → UI Primitives: uses · Navigation built from shared primitives
- Diagnose Page → Diagnose Client: mounts · Page delegates workflow to client orchestrator
- History Page → History API: loads · History page fetches stored records
- Diagnose Client → Voice Recorder: captures · Collects audio input
- Diagnose Client → Leaf Uploader: captures · Collects image/file input
- Diagnose Client → Location Picker: captures · Collects location context
- Diagnose Client → Transcribe API: calls · Sends audio for transcription
- Diagnose Client → Analyze API: calls · Submits combined diagnosis inputs
- Diagnose Client → Results Panel: renders · Displays analysis output
- Transcribe API → Firebase Admin: may use · Trusted server-side access boundary
- Analyze API → Firebase Admin: may use · Trusted server-side access boundary
- History API → Firebase Admin: uses · Reads persisted history via admin access
- Auth Provider → Firebase Client: uses · Client authentication and app state
- History API → Shared Types: shares · Structured history records
- Analyze API → Shared Types: shares · Analysis request/response shapes
- Diagnose Client → Shared Types: uses · Client-side workflow data contracts
- UI Primitives → Utils: supported by · Shared helper utilities
- UI Primitives → Button Variants: uses · Variant styling source
- Results Panel → UI Primitives: uses · Built from reusable UI primitives
- Diagnose Client → UI Primitives: uses · Workflow UI composed from shared primitives
- Landing → UI Primitives: uses · Landing page uses shared primitives
- History Page → UI Primitives: uses · History page uses shared primitives
