# himanijha/foldednotes architecture

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

- Interactive diagram: https://gitdiagram.com/himanijha/foldednotes
- Repository: https://github.com/himanijha/foldednotes

## Overview

1. **Overall shape**
   - This is a **Next.js Pages Router** application with both UI pages and backend API routes in the same repo.
   - The architecture is split into:
     - **Client-facing pages/components** under `src/pages` and `src/components`
     - **Server-side API endpoints** under `src/pages/api`
     - **Shared domain/infrastructure helpers** under `src/lib`
     - A small **custom server layer** under `src/server` plus `server.js`

2. **Primary product flow**
   - The app is built around **anonymous voice messages**: users record audio, submit it for transcription/processing, and then consume or generate content from that transcript.
   - The README also calls out a **notes feed** where users can post short notes, including a side-panel “write a note” workflow.

3. **Frontend entry points**
   - Main UI screens live in:
     - `src/pages/index.tsx` and `src/pages/home.tsx` for landing/home
     - `src/pages/record.tsx` for audio capture
     - `src/pages/generate.tsx` for transcript-driven generation
     - `src/pages/memories.tsx` for saved/archived content
     - `src/pages/login.tsx` and `src/pages/settings.tsx`
   - `_app.tsx` and `_document.tsx` provide shared app-level wiring and document setup.
   - Styling is page/component-scoped via CSS modules in `src/styles` plus global styles.

4. **Client components and UX boundaries**
   - `AudioRecorder.tsx` is the main recording UI component; it likely owns microphone capture, recording state, and upload/submit actions.
   - `GenerateFromTranscript.tsx` appears to handle turning a transcript into generated content or follow-up artifacts.
   - These components are the primary bridge from user interaction into the API layer.

5. **API layer as the backend boundary**
   - The app uses Next.js API routes as its server boundary. Key endpoints include:
     - `POST /api/auth/login`, `signup`, `me`
     - `POST /api/notes`
     - `POST /api/transcribe`
     - `POST /api/summary`
     - `POST /api/classify`
     - `POST /api/speech`
     - `GET/POST /api/voices`, `/api/pick-voice`
     - `GET/POST /api/recordings`
   - This means the browser never talks directly to MongoDB or third-party AI services; it goes through these routes.

6. **Identity and session subsystem**
   - `src/lib/auth.ts` and the auth API routes indicate a dedicated authentication subsystem.
   - The presence of `/api/auth/me` suggests the frontend can hydrate the current user/session state from the backend.
   - The repo supports authenticated flows for some actions while still emphasizing anonymous contributions as a product concept.

7. **Persistence layer**
   - MongoDB is the main database, with connection helpers in `src/lib/mongodb.ts` and `src/server/mongodb.ts`.
   - Data likely persisted here includes:
     - Users/auth records
     - Notes/feed items
     - Recordings and transcript metadata
     - Possibly summaries, classifications, and selected voice preferences
   - `src/pages/api/recordings.ts` and `src/pages/api/notes.ts` are the clearest persistence-facing endpoints.

8. **AI/LLM processing subsystem**
   - `src/lib/gemini.ts` and `src/lib/prompt.ts` show an LLM-backed generation layer, likely used for summarization, rewriting, or content generation from transcripts.
   - `/api/summary` and `/api/classify` are the service boundaries for turning raw transcript content into structured outputs.
   - `src/lib/emotions.ts` and `src/types/emotion.ts` suggest a dedicated emotion/labeling model used in classification or content tagging.

9. **Audio and speech subsystem**
   - `src/lib/audio.ts` handles audio-specific transformations or transport concerns.
   - The README documents `POST /api/transcribe` as an **ElevenLabs Speech-to-Text** integration using base64-encoded audio.
   - `POST /api/speech`, `/api/voices`, and `/api/pick-voice` indicate a text-to-speech / voice-selection pipeline, also likely external-service-backed.
   - This makes audio an explicit data pipeline:
     - browser recording → API upload → transcription → transcript processing → optional speech/voice output

10. **External service dependencies**
   - **ElevenLabs** is a required external service for transcription, and likely also voice generation.
   - **Gemini** is used for AI text processing/generation.
   - **MongoDB** is the persistence backend.
   - These are the main off-repo dependencies that affect architecture and deployment configuration.

11. **Custom server and runtime**
   - `server.js` plus `src/server/index.ts` suggest there is a custom Node server entrypoint or server bootstrap in addition to Next.js defaults.
   - This is relevant because it may control startup behavior, database initialization, or route mounting beyond standard Next.js deployment.
   - The project still remains fundamentally a **Next.js app**, but with server-side bootstrap logic layered on top.

12. **End-to-end data flow summary**
   - Typical flow:
     - User records audio in the browser
     - Client submits audio to `/api/transcribe`
     - Transcript may then be sent to `/api/summary`, `/api/classify`, or `/api/speech`
     - Results and/or notes are persisted through MongoDB-backed API routes
     - The UI retrieves user state and content through API routes like `/api/me`, `/api/notes`, and `/api/recordings`

13. **Architectural boundaries to show in a diagram**
   - **Presentation layer:** pages + reusable React components
   - **API layer:** Next.js route handlers under `/api/*`
   - **Domain helpers:** auth, audio, prompts, emotions, AI integration
   - **Data layer:** MongoDB
   - **External AI services:** ElevenLabs and Gemini
   - **Static assets/styles:** `public` and `src/styles`

Main entry points: [`src/pages/api/summary.ts`](https://github.com/himanijha/foldednotes/blob/main/src/pages/api/summary.ts) (AI API), [`src/pages/api/transcribe.ts`](https://github.com/himanijha/foldednotes/blob/main/src/pages/api/transcribe.ts) (Speech API), [`src/lib/mongodb.ts`](https://github.com/himanijha/foldednotes/blob/main/src/lib/mongodb.ts) (MongoDB), [`src/pages/_app.tsx`](https://github.com/himanijha/foldednotes/blob/main/src/pages/_app.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_app_shell["App shell<br/>next app wrapper<br/>[_app.tsx]"]
  node_landing["Landing<br/>page<br/>[index.tsx]"]
  node_record_page["Record<br/>page<br/>[record.tsx]"]
  node_generate_page["Generate<br/>page<br/>[generate.tsx]"]
  node_memories_page["Memories<br/>page<br/>[memories.tsx]"]
  node_account_pages["Account<br/>page set<br/>[login.tsx]"]
end

subgraph group_components["Components"]
  node_audio_recorder["AudioRecorder<br/>recorder ui<br/>[AudioRecorder.tsx]"]
  node_generate_from_transcript["Transcript UI<br/>generation ui"]
end

subgraph group_api["API Layer"]
  node_auth_api["Auth API<br/>route group<br/>[login.ts]"]
  node_notes_api["Notes API<br/>route<br/>[notes.ts]"]
  node_recordings_api["Recordings API<br/>route<br/>[recordings.ts]"]
  node_speech_api["Speech API<br/>route group<br/>[transcribe.ts]"]
  node_ai_api["AI API<br/>route group<br/>[summary.ts]"]
  node_voices_api["Voices API<br/>route group<br/>[voices.ts]"]
  node_hello_api(("Hello<br/>route<br/>[hello.ts]"))
end

subgraph group_domain["Domain"]
  node_auth_lib["Auth core<br/>auth helper<br/>[auth.ts]"]
  node_audio_lib["Audio core<br/>audio helper<br/>[audio.ts]"]
  node_prompt_lib["Prompting<br/>llm helper<br/>[prompt.ts]"]
  node_emotion_lib["Emotions<br/>label model<br/>[emotions.ts]"]
  node_gemini_lib["Gemini client<br/>llm client<br/>[gemini.ts]"]
end

subgraph group_data["Persistence"]
  node_mongodb_lib[("MongoDB<br/>db helper<br/>[mongodb.ts]")]
  node_server_boot["Server bootstrap<br/>node server<br/>[server.js]"]
  node_server_mongo[("Server Mongo<br/>db bootstrap<br/>[mongodb.ts]")]
  node_next_server["Server core<br/>server runtime<br/>[index.ts]"]
end

subgraph group_external["External Services"]
  node_elevenlabs(("ElevenLabs<br/>speech service"))
  node_google_gemini(("Gemini<br/>ai service"))
  node_mongo_cloud[("MongoDB<br/>database service")]
end

node_app_shell -->|"wraps"| node_landing
node_app_shell -->|"wraps"| node_record_page
node_app_shell -->|"wraps"| node_generate_page
node_landing -->|"uses"| node_audio_recorder
node_record_page -->|"uses"| node_audio_recorder
node_generate_page -->|"uses"| node_generate_from_transcript
node_account_pages -->|"calls"| node_auth_api
node_audio_recorder -->|"submits audio"| node_speech_api
node_generate_from_transcript -->|"requests output"| node_ai_api
node_generate_from_transcript -->|"may save"| node_notes_api
node_memories_page -->|"loads"| node_notes_api
node_record_page -->|"persists"| node_recordings_api
node_auth_api -->|"implements"| node_auth_lib
node_notes_api -->|"stores"| node_mongodb_lib
node_recordings_api -->|"stores"| node_mongodb_lib
node_speech_api -->|"uses"| node_audio_lib
node_speech_api -->|"calls"| node_elevenlabs
node_voices_api -->|"calls"| node_elevenlabs
node_ai_api -->|"uses"| node_prompt_lib
node_ai_api -->|"calls"| node_gemini_lib
node_ai_api -->|"uses"| node_emotion_lib
node_mongodb_lib -->|"connects"| node_mongo_cloud
node_server_boot -->|"starts"| node_next_server
node_next_server -->|"initializes"| node_server_mongo
node_server_mongo -->|"connects"| node_mongo_cloud
node_auth_api -->|"stores"| node_mongodb_lib
node_speech_api -.->|"may persist"| node_mongo_cloud
node_ai_api -.->|"may persist"| node_mongo_cloud
node_hello_api -->|"served by"| node_next_server

click node_app_shell "https://github.com/himanijha/foldednotes/blob/main/src/pages/_app.tsx"
click node_landing "https://github.com/himanijha/foldednotes/blob/main/src/pages/index.tsx"
click node_record_page "https://github.com/himanijha/foldednotes/blob/main/src/pages/record.tsx"
click node_generate_page "https://github.com/himanijha/foldednotes/blob/main/src/pages/generate.tsx"
click node_memories_page "https://github.com/himanijha/foldednotes/blob/main/src/pages/memories.tsx"
click node_account_pages "https://github.com/himanijha/foldednotes/blob/main/src/pages/login.tsx"
click node_audio_recorder "https://github.com/himanijha/foldednotes/blob/main/src/components/AudioRecorder.tsx"
click node_generate_from_transcript "https://github.com/himanijha/foldednotes/blob/main/src/components/GenerateFromTranscript.tsx"
click node_auth_api "https://github.com/himanijha/foldednotes/blob/main/src/pages/api/auth/login.ts"
click node_notes_api "https://github.com/himanijha/foldednotes/blob/main/src/pages/api/notes.ts"
click node_recordings_api "https://github.com/himanijha/foldednotes/blob/main/src/pages/api/recordings.ts"
click node_speech_api "https://github.com/himanijha/foldednotes/blob/main/src/pages/api/transcribe.ts"
click node_ai_api "https://github.com/himanijha/foldednotes/blob/main/src/pages/api/summary.ts"
click node_voices_api "https://github.com/himanijha/foldednotes/blob/main/src/pages/api/voices.ts"
click node_hello_api "https://github.com/himanijha/foldednotes/blob/main/src/pages/api/hello.ts"
click node_auth_lib "https://github.com/himanijha/foldednotes/blob/main/src/lib/auth.ts"
click node_audio_lib "https://github.com/himanijha/foldednotes/blob/main/src/lib/audio.ts"
click node_prompt_lib "https://github.com/himanijha/foldednotes/blob/main/src/lib/prompt.ts"
click node_emotion_lib "https://github.com/himanijha/foldednotes/blob/main/src/lib/emotions.ts"
click node_gemini_lib "https://github.com/himanijha/foldednotes/blob/main/src/lib/gemini.ts"
click node_mongodb_lib "https://github.com/himanijha/foldednotes/blob/main/src/lib/mongodb.ts"
click node_server_boot "https://github.com/himanijha/foldednotes/blob/main/server.js"
click node_server_mongo "https://github.com/himanijha/foldednotes/blob/main/src/server/mongodb.ts"
click node_next_server "https://github.com/himanijha/foldednotes/blob/main/src/server/index.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_app_shell,node_landing,node_record_page,node_generate_page,node_memories_page,node_account_pages toneBlue
class node_audio_recorder,node_generate_from_transcript toneAmber
class node_auth_api,node_notes_api,node_recordings_api,node_speech_api,node_ai_api,node_voices_api,node_hello_api toneMint
class node_auth_lib,node_audio_lib,node_prompt_lib,node_emotion_lib,node_gemini_lib toneRose
class node_mongodb_lib,node_server_boot,node_server_mongo,node_next_server toneIndigo
class node_elevenlabs,node_google_gemini,node_mongo_cloud toneTeal
```

## Components

### Presentation

UI pages and shared app shell

- [App shell](https://github.com/himanijha/foldednotes/blob/main/src/pages/_app.tsx): next app wrapper · Global app and document setup · `src/pages/_app.tsx`
- [Landing](https://github.com/himanijha/foldednotes/blob/main/src/pages/index.tsx): page · Entry and home screens · `src/pages/index.tsx`
- [Record](https://github.com/himanijha/foldednotes/blob/main/src/pages/record.tsx): page · Audio capture workflow · `src/pages/record.tsx`
- [Generate](https://github.com/himanijha/foldednotes/blob/main/src/pages/generate.tsx): page · Transcript-driven generation screen · `src/pages/generate.tsx`
- [Memories](https://github.com/himanijha/foldednotes/blob/main/src/pages/memories.tsx): page · Saved and archived content · `src/pages/memories.tsx`
- [Account](https://github.com/himanijha/foldednotes/blob/main/src/pages/login.tsx): page set · Login and settings screens · `src/pages/login.tsx`

### Components

Reusable client interactions

- [AudioRecorder](https://github.com/himanijha/foldednotes/blob/main/src/components/AudioRecorder.tsx): recorder ui · Microphone capture and upload control · `src/components/AudioRecorder.tsx`
- [Transcript UI](https://github.com/himanijha/foldednotes/blob/main/src/components/GenerateFromTranscript.tsx): generation ui · Turns transcripts into follow-up content · `src/components/GenerateFromTranscript.tsx`

### API Layer

Next.js route handlers

- [Auth API](https://github.com/himanijha/foldednotes/blob/main/src/pages/api/auth/login.ts): route group · Login, signup, and session lookup · `src/pages/api/auth/login.ts`
- [Notes API](https://github.com/himanijha/foldednotes/blob/main/src/pages/api/notes.ts): route · Create and read notes feed items · `src/pages/api/notes.ts`
- [Recordings API](https://github.com/himanijha/foldednotes/blob/main/src/pages/api/recordings.ts): route · Persist recording metadata and history · `src/pages/api/recordings.ts`
- [Speech API](https://github.com/himanijha/foldednotes/blob/main/src/pages/api/transcribe.ts): route group · Transcription and voice synthesis endpoints · `src/pages/api/transcribe.ts`
- [AI API](https://github.com/himanijha/foldednotes/blob/main/src/pages/api/summary.ts): route group · Summaries and classification endpoints · `src/pages/api/summary.ts`
- [Voices API](https://github.com/himanijha/foldednotes/blob/main/src/pages/api/voices.ts): route group · Voice listing and selection endpoints · `src/pages/api/voices.ts`
- [Hello](https://github.com/himanijha/foldednotes/blob/main/src/pages/api/hello.ts): route · Basic health or sample endpoint · `src/pages/api/hello.ts`

### Domain

Shared auth, audio, and AI helpers

- [Auth core](https://github.com/himanijha/foldednotes/blob/main/src/lib/auth.ts): auth helper · Session and identity logic · `src/lib/auth.ts`
- [Audio core](https://github.com/himanijha/foldednotes/blob/main/src/lib/audio.ts): audio helper · Audio processing and transport utilities · `src/lib/audio.ts`
- [Prompting](https://github.com/himanijha/foldednotes/blob/main/src/lib/prompt.ts): llm helper · Prompt templates and generation helpers · `src/lib/prompt.ts`
- [Emotions](https://github.com/himanijha/foldednotes/blob/main/src/lib/emotions.ts): label model · Emotion and classification vocabulary · `src/lib/emotions.ts`
- [Gemini client](https://github.com/himanijha/foldednotes/blob/main/src/lib/gemini.ts): llm client · AI integration for text generation · `src/lib/gemini.ts`

### Persistence

MongoDB access and server bootstrap

- [MongoDB](https://github.com/himanijha/foldednotes/blob/main/src/lib/mongodb.ts): db helper · Database connection helper · `src/lib/mongodb.ts`
- [Server bootstrap](https://github.com/himanijha/foldednotes/blob/main/server.js): node server · Custom server entrypoint and startup logic · `server.js`
- [Server Mongo](https://github.com/himanijha/foldednotes/blob/main/src/server/mongodb.ts): db bootstrap · Server-side database wiring · `src/server/mongodb.ts`
- [Server core](https://github.com/himanijha/foldednotes/blob/main/src/server/index.ts): server runtime · Custom server implementation · `src/server/index.ts`

### External Services

Off-repo AI, speech, and database dependencies

- **ElevenLabs**: speech service · Transcription and voice generation
- **Gemini**: ai service · LLM-backed text processing
- **MongoDB**: database service · Persistent data store

## Connections

- App shell → Landing: wraps · Shared app-level setup for pages
- App shell → Record: wraps · Shared app-level setup for pages
- App shell → Generate: wraps · Shared app-level setup for pages
- Landing → AudioRecorder: uses · Landing and recording flows surface recorder UI
- Record → AudioRecorder: uses · Primary capture interaction
- Generate → Transcript UI: uses · Transcript-driven generation UI
- Account → Auth API: calls · Login and session management
- AudioRecorder → Speech API: submits audio · Uploads recorded audio for transcription
- Transcript UI → AI API: requests output · Uses transcript processing endpoints
- Transcript UI → Notes API: may save · Generated content can become notes
- Memories → Notes API: loads · Reads stored notes and memories
- Record → Recordings API: persists · Stores recording history
- Auth API → Auth core: implements · Auth route handlers use shared auth logic
- Notes API → MongoDB: stores · Persists notes data
- Recordings API → MongoDB: stores · Persists recording metadata
- Speech API → Audio core: uses · Audio encoding and transport helpers
- Speech API → ElevenLabs: calls · Transcription and voice services
- Voices API → ElevenLabs: calls · Voice catalog and selection data
- AI API → Prompting: uses · Builds prompts for AI tasks
- AI API → Gemini client: calls · LLM-backed summary and classification
- AI API → Emotions: uses · Emotion labels for classification
- MongoDB → MongoDB: connects · Primary persistence backend
- Server bootstrap → Server core: starts · Custom runtime entrypoint
- Server core → Server Mongo: initializes · Server-side Mongo wiring
- Server Mongo → MongoDB: connects · Database connection used by server bootstrap
- Auth API → MongoDB: stores · Auth records and session state
- Speech API → MongoDB: may persist · Transcript or recording metadata
- AI API → MongoDB: may persist · Generated summaries or labels
- Hello → Server core: served by · Example or health route in the API surface