# amritkaur15/gather architecture

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

- Interactive diagram: https://gitdiagram.com/amritkaur15/gather
- Repository: https://github.com/amritkaur15/gather

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** application with a fairly strong separation between **UI components**, **server API routes**, and **domain/service libraries**.
   - The core product appears to be a **notes workspace** with **collections, tags, imports, AI assistance, search, and duplicate handling**.

2. **Presentation layer**
   - The main client-side structure lives under `src/components` and `src/app`.
   - `src/components/layout` contains the shell of the app: sidebar, note list, editor panel, and the top-level app shell.
   - `src/components/editor` is responsible for rich-text editing, centered around **Tiptap**.
   - `src/components/ai`, `src/components/import`, and `src/components/ui` provide feature-specific modals/panels used by the main workspace.

3. **Route structure and page boundaries**
   - The app uses route groups for **authenticated app pages** and **auth pages**:
     - `src/app/(app)/app/page.tsx` for the logged-in workspace.
     - `src/app/(auth)/login` and `src/app/(auth)/register` for authentication flows.
   - The root `src/app/page.tsx` is a separate landing entry point.
   - This split is important because it marks the boundary between public access, auth, and the internal note-management UI.

4. **Server API layer**
   - Nearly all product behavior is exposed through **Next.js route handlers** in `src/app/api`.
   - The API is organized by domain:
     - `notes`, `collections`, `tags`
     - `import`
     - `duplicates`
     - `suggestions`
     - `ai`
     - `auth`
   - This suggests the UI mostly talks to the backend through internal HTTP endpoints rather than direct database access from components.

5. **Domain/service layer**
   - The actual business logic sits in `src/lib/*` rather than in the route files.
   - Each domain has a dedicated service module:
     - `src/lib/notes/service.ts`
     - `src/lib/collections/service.ts`
     - `src/lib/tags/service.ts`
     - `src/lib/import/service.ts`
   - This is the main application boundary: **route handler → service → database / AI / import utilities**.

6. **Persistence and schema**
   - Database access is centralized in `src/lib/db`, with schema definitions in `src/lib/db/schema.ts`.
   - Migrations are managed by **Drizzle** under `drizzle/migrations`, showing that schema evolution is first-class.
   - The presence of a `search_index` migration indicates a persistent search layer, likely used for text search and/or embeddings-backed retrieval.

7. **Authentication and session model**
   - Authentication is implemented with **NextAuth** via `src/lib/auth/config.ts` and `src/app/api/auth/[...nextauth]/route.ts`.
   - There is also a custom registration route at `src/app/api/auth/register/route.ts`.
   - `src/components/SessionProvider.tsx` bridges auth state into the client-side app, so authenticated UI likely depends on session context.

8. **Notes, collections, and tags domain**
   - Notes are the central entity, with supporting hierarchy and categorization through **collections** and **tags**.
   - Related routes include note CRUD, archived notes, merge, duplicate checking, title versioning, collection-note membership, and tag-note membership.
   - This indicates a mature note lifecycle: create/edit, organize, archive, merge, and reconcile duplicates.

9. **Rich text and editor model**
   - The editor is built around **Tiptap**, and the repo contains explicit conversion utilities in `src/lib/notes/tiptap.ts` and `src/lib/import/toTiptapJSON.ts`.
   - Import pipelines and the editor both converge on a **Tiptap JSON document model**, which is the internal content representation.
   - This is a key architectural boundary: external formats are normalized into the editor’s native document structure.

10. **Import subsystem**
   - Import is a standalone pipeline with both client and server pieces:
     - Client processing in `src/lib/import/client`
     - Parsers for `apple-notes`, `pdf`, `text`, and `zip`
     - Transformation utilities for HTML/Markdown to Tiptap
   - API routes support import preview, job tracking, and PDF direct import.
   - The presence of `qualityScorer.ts` suggests imported content is evaluated before being accepted or transformed, not just blindly ingested.

11. **AI subsystem**
   - AI functionality is split into focused server libraries: `categorise`, `chat`, `duplicates`, `embeddings`, `search`, and `suggestions`.
   - API routes expose AI categorization and chat capabilities.
   - The structure implies AI is used for **assistive workflows** rather than as the core data store: categorization, duplicate assistance, search augmentation, and note suggestions.

12. **Search and retrieval**
   - Search has both a dedicated API route and AI support libraries, plus database support via a search-index migration.
   - This implies a layered search architecture: database-backed indexing plus AI/embedding-based retrieval or ranking.
   - Search is likely integrated into the note workspace rather than being a standalone feature.

13. **Cross-cutting concerns**
   - `src/lib/rateLimit.ts` shows request throttling as a shared backend concern, likely for auth, AI, or import endpoints.
   - `src/styles/themes.css`, `src/lib/theme/*`, and `src/components/ui/ThemeToggle.tsx` show theming is a cross-cutting UI system rather than a per-page concern.
   - These utilities sit outside domain services and affect multiple features.

14. **Testing and verification**
   - The `tests` directory mirrors the production structure: API, lib/ai, lib/import, lib/notes, lib/collections, and lib/tags.
   - This indicates the architecture is designed around testable service boundaries, with most business rules isolated from React components.
   - The strongest unit boundaries are in `lib/*`, not in route handlers or UI.

15. **Key architecture takeaway**
   - The repository is best understood as a **domain-driven notes application** built on Next.js:
     - UI shell and editor on the client
     - Route handlers as transport/API boundaries
     - `lib/*` as the business-logic layer
     - Drizzle/Postgres-style persistence underneath
     - AI and import subsystems as specialized pipelines feeding the same note model
   - For an architecture diagram, the central hub should be the **note/document model**, with collections, tags, AI, import, search, and duplicates all radiating around it.

Main entry points: [`src/components/layout/AppShell.tsx`](https://github.com/amritkaur15/gather/blob/main/src/components/layout/AppShell.tsx) (App shell), [`src/lib/ai/chat.ts`](https://github.com/amritkaur15/gather/blob/main/src/lib/ai/chat.ts) (AI suite), [`src/lib/notes/service.ts`](https://github.com/amritkaur15/gather/blob/main/src/lib/notes/service.ts) (Notes svc), [`src/lib/import/service.ts`](https://github.com/amritkaur15/gather/blob/main/src/lib/import/service.ts) (Import svc)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App routes"]
  node_landing["Landing<br/>public page<br/>[page.tsx]"]
  node_workspace["Workspace<br/>app page<br/>[page.tsx]"]
  node_login["Login<br/>auth page<br/>[page.tsx]"]
  node_register["Register<br/>auth page<br/>[page.tsx]"]
end

subgraph group_api["API routes"]
  node_noteapi["Notes API<br/>route handlers"]
  node_catalogapi["Catalog API<br/>route handlers"]
  node_importapi["Import API<br/>route handlers"]
  node_aiapi["AI API<br/>route handlers"]
  node_authapi["Auth API<br/>route handlers"]
end

subgraph group_components["UI components"]
  node_appshell["App shell<br/>workspace shell<br/>[AppShell.tsx]"]
  node_editor["Editor<br/>rich text<br/>[TiptapEditor.tsx]"]
  node_sidebar["Sidebar<br/>navigation<br/>[Sidebar.tsx]"]
  node_notelist["Note list<br/>list view<br/>[NoteList.tsx]"]
  node_panels["Feature panels<br/>modals<br/>[AIChatPanel.tsx]"]
  node_session(("Session<br/>auth bridge"))
end

subgraph group_lib["Domain libs"]
  node_notesvc["Notes svc<br/>domain service<br/>[service.ts]"]
  node_catalogsvc["Catalog svc<br/>domain service<br/>[service.ts]"]
  node_importsvc["Import svc<br/>pipeline service<br/>[service.ts]"]
  node_aisvc["AI suite<br/>assistive services<br/>[chat.ts]"]
  node_authcfg["Auth config<br/>[config.ts]"]
end

subgraph group_db["Data layer"]
  node_db[("Database<br/>drizzle client<br/>[schema.ts]")]
  node_migrations["Migrations<br/>schema history"]
end

subgraph group_tests["Tests"]
  node_notesvc_test["Notes tests<br/>service tests<br/>[service.test.ts]"]
  node_importsvc_test["Import tests<br/>pipeline tests<br/>[service.test.ts]"]
end

node_landing -->|"entry"| node_workspace
node_workspace -->|"renders"| node_appshell
node_login -->|"auth"| node_authapi
node_register -->|"signup"| node_authapi
node_appshell -->|"contains"| node_sidebar
node_appshell -->|"contains"| node_notelist
node_appshell -->|"contains"| node_editor
node_appshell -->|"opens"| node_panels
node_session -->|"hydrates"| node_workspace
node_editor -->|"saves"| node_noteapi
node_notelist -->|"loads"| node_noteapi
node_sidebar -->|"navigates"| node_catalogapi
node_panels -->|"uses"| node_aiapi
node_panels -->|"uses"| node_importapi
node_noteapi -->|"delegates"| node_notesvc
node_catalogapi -->|"delegates"| node_catalogsvc
node_importapi -->|"delegates"| node_importsvc
node_aiapi -->|"delegates"| node_aisvc
node_authapi -->|"configures"| node_authcfg
node_notesvc -->|"persists"| node_db
node_catalogsvc -->|"persists"| node_db
node_importsvc -->|"stores"| node_db
node_aisvc -->|"reads"| node_db
node_aisvc -.->|"indexes"| node_migrations
node_notesvc -.->|"duplicates"| node_aisvc
node_importsvc -.->|"enhances"| node_aisvc
node_notesvc_test -.->|"verifies"| node_notesvc
node_importsvc_test -.->|"verifies"| node_importsvc

click node_landing "https://github.com/amritkaur15/gather/blob/main/src/app/page.tsx"
click node_workspace "https://github.com/amritkaur15/gather/blob/main/src/app/(app)/app/page.tsx"
click node_login "https://github.com/amritkaur15/gather/blob/main/src/app/(auth)/login/page.tsx"
click node_register "https://github.com/amritkaur15/gather/blob/main/src/app/(auth)/register/page.tsx"
click node_appshell "https://github.com/amritkaur15/gather/blob/main/src/components/layout/AppShell.tsx"
click node_editor "https://github.com/amritkaur15/gather/blob/main/src/components/editor/TiptapEditor.tsx"
click node_sidebar "https://github.com/amritkaur15/gather/blob/main/src/components/layout/Sidebar.tsx"
click node_notelist "https://github.com/amritkaur15/gather/blob/main/src/components/layout/NoteList.tsx"
click node_panels "https://github.com/amritkaur15/gather/blob/main/src/components/ai/AIChatPanel.tsx"
click node_session "https://github.com/amritkaur15/gather/blob/main/src/components/SessionProvider.tsx"
click node_noteapi "https://github.com/amritkaur15/gather/tree/main/src/app/api/notes"
click node_catalogapi "https://github.com/amritkaur15/gather/tree/main/src/app/api/collections"
click node_importapi "https://github.com/amritkaur15/gather/tree/main/src/app/api/import"
click node_aiapi "https://github.com/amritkaur15/gather/tree/main/src/app/api/ai"
click node_authapi "https://github.com/amritkaur15/gather/tree/main/src/app/api/auth"
click node_notesvc "https://github.com/amritkaur15/gather/blob/main/src/lib/notes/service.ts"
click node_catalogsvc "https://github.com/amritkaur15/gather/blob/main/src/lib/collections/service.ts"
click node_importsvc "https://github.com/amritkaur15/gather/blob/main/src/lib/import/service.ts"
click node_aisvc "https://github.com/amritkaur15/gather/blob/main/src/lib/ai/chat.ts"
click node_authcfg "https://github.com/amritkaur15/gather/blob/main/src/lib/auth/config.ts"
click node_db "https://github.com/amritkaur15/gather/blob/main/src/lib/db/schema.ts"
click node_migrations "https://github.com/amritkaur15/gather/tree/main/drizzle/migrations"
click node_notesvc_test "https://github.com/amritkaur15/gather/blob/main/tests/lib/notes/service.test.ts"
click node_importsvc_test "https://github.com/amritkaur15/gather/blob/main/tests/lib/import/service.test.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_workspace,node_login,node_register toneBlue
class node_noteapi,node_catalogapi,node_importapi,node_aiapi,node_authapi toneAmber
class node_appshell,node_editor,node_sidebar,node_notelist,node_panels,node_session toneMint
class node_notesvc,node_catalogsvc,node_importsvc,node_aisvc,node_authcfg toneRose
class node_db,node_migrations toneIndigo
class node_notesvc_test,node_importsvc_test toneTeal
```

## Components

### App routes

Public, auth, and workspace route boundaries.

- [Landing](https://github.com/amritkaur15/gather/blob/main/src/app/page.tsx): public page · Root marketing or entry page. · `src/app/page.tsx`
- [Workspace](https://github.com/amritkaur15/gather/blob/main/src/app/(app)/app/page.tsx): app page · Authenticated note workspace shell. · `src/app/(app)/app/page.tsx`
- [Login](https://github.com/amritkaur15/gather/blob/main/src/app/(auth)/login/page.tsx): auth page · Sign-in flow. · `src/app/(auth)/login/page.tsx`
- [Register](https://github.com/amritkaur15/gather/blob/main/src/app/(auth)/register/page.tsx): auth page · Account creation flow. · `src/app/(auth)/register/page.tsx`

### API routes

Next.js route handlers organized by domain.

- [Notes API](https://github.com/amritkaur15/gather/tree/main/src/app/api/notes): route handlers · CRUD, archive, merge, search, formatting, duplicate checks. · `src/app/api/notes`
- [Catalog API](https://github.com/amritkaur15/gather/tree/main/src/app/api/collections): route handlers · Collections and tags membership and CRUD endpoints. · `src/app/api/collections`
- [Import API](https://github.com/amritkaur15/gather/tree/main/src/app/api/import): route handlers · Import preview, jobs, and PDF direct ingest. · `src/app/api/import`
- [AI API](https://github.com/amritkaur15/gather/tree/main/src/app/api/ai): route handlers · Categorisation and chat endpoints. · `src/app/api/ai`
- [Auth API](https://github.com/amritkaur15/gather/tree/main/src/app/api/auth): route handlers · NextAuth session and registration endpoints. · `src/app/api/auth`

### UI components

Client-side workspace, editor, auth, and feature panels.

- [App shell](https://github.com/amritkaur15/gather/blob/main/src/components/layout/AppShell.tsx): workspace shell · Main layout coordinating sidebar, list, and editor. · `src/components/layout/AppShell.tsx`
- [Editor](https://github.com/amritkaur15/gather/blob/main/src/components/editor/TiptapEditor.tsx): rich text · Tiptap-based note editor and toolbar. · `src/components/editor/TiptapEditor.tsx`
- [Sidebar](https://github.com/amritkaur15/gather/blob/main/src/components/layout/Sidebar.tsx): navigation · Collection and workspace navigation. · `src/components/layout/Sidebar.tsx`
- [Note list](https://github.com/amritkaur15/gather/blob/main/src/components/layout/NoteList.tsx): list view · Browse and select notes. · `src/components/layout/NoteList.tsx`
- [Feature panels](https://github.com/amritkaur15/gather/blob/main/src/components/ai/AIChatPanel.tsx): modals · AI, import, duplicate, and context UI surfaces. · `src/components/ai/AIChatPanel.tsx`
- [Session](https://github.com/amritkaur15/gather/blob/main/src/components/SessionProvider.tsx): auth bridge · Client session provider for authenticated UI. · `src/components/SessionProvider.tsx`

### Domain libs

Business logic, AI, import, auth, and persistence helpers.

- [Notes svc](https://github.com/amritkaur15/gather/blob/main/src/lib/notes/service.ts): domain service · Note lifecycle, formatting, archive, merge, duplicate logic. · `src/lib/notes/service.ts`
- [Catalog svc](https://github.com/amritkaur15/gather/blob/main/src/lib/collections/service.ts): domain service · Collections and tags business rules. · `src/lib/collections/service.ts`
- [Import svc](https://github.com/amritkaur15/gather/blob/main/src/lib/import/service.ts): pipeline service · Import orchestration, parsing, processing, and Tiptap conversion. · `src/lib/import/service.ts`
- [AI suite](https://github.com/amritkaur15/gather/blob/main/src/lib/ai/chat.ts): assistive services · Categorise, chat, embeddings, search, duplicates, and suggestions. · `src/lib/ai/chat.ts`
- [Auth config](https://github.com/amritkaur15/gather/blob/main/src/lib/auth/config.ts): nextauth config · Server auth strategy and session configuration. · `src/lib/auth/config.ts`

### Data layer

Database client and schema/migrations.

- [Database](https://github.com/amritkaur15/gather/blob/main/src/lib/db/schema.ts): drizzle client · Database client and schema definitions. · `src/lib/db/schema.ts`
- [Migrations](https://github.com/amritkaur15/gather/tree/main/drizzle/migrations): schema history · Drizzle migration history including search indexing. · `drizzle/migrations`

### Tests

Service-oriented verification mirroring production boundaries.

- [Notes tests](https://github.com/amritkaur15/gather/blob/main/tests/lib/notes/service.test.ts): service tests · Verification for note domain behavior. · `tests/lib/notes/service.test.ts`
- [Import tests](https://github.com/amritkaur15/gather/blob/main/tests/lib/import/service.test.ts): pipeline tests · Verification for parsing and transformation pipeline. · `tests/lib/import/service.test.ts`

## Connections

- Landing → Workspace: entry · Public entry leads into the authenticated workspace.
- Workspace → App shell: renders · Workspace page mounts the main app shell.
- Login → Auth API: auth · Login flow relies on auth endpoints and NextAuth session handling.
- Register → Auth API: signup · Registration form posts to custom registration endpoint.
- App shell → Sidebar: contains · Shell composes the primary navigation.
- App shell → Note list: contains · Shell composes the note browser.
- App shell → Editor: contains · Shell composes the document editor.
- App shell → Feature panels: opens · Shell exposes feature panels and dialogs.
- Session → Workspace: hydrates · Session context enables authenticated workspace behavior.
- Editor → Notes API: saves · Editor persists note content and formatting through note APIs.
- Note list → Notes API: loads · List fetches and updates notes via the notes API.
- Sidebar → Catalog API: navigates · Sidebar drives collection and tag organization through catalog endpoints.
- Feature panels → AI API: uses · AI panels call categorisation and chat endpoints.
- Feature panels → Import API: uses · Import modal uses preview and job APIs.
- Notes API → Notes svc: delegates · Route handlers forward note operations to domain service logic.
- Catalog API → Catalog svc: delegates · Collection and tag routes forward to catalog services.
- Import API → Import svc: delegates · Import routes invoke parsing and processing pipeline logic.
- AI API → AI suite: delegates · AI routes call assistive service modules.
- Auth API → Auth config: configures · Auth routes are backed by NextAuth configuration.
- Notes svc → Database: persists · Notes service reads and writes structured note data.
- Catalog svc → Database: persists · Collections and tags are stored in the database.
- Import svc → Database: stores · Imported notes and jobs are persisted.
- AI suite → Database: reads · AI workflows consume stored notes and indexes.
- AI suite → Migrations: indexes · Search and retrieval depend on schema evolution and search index support.
- Notes svc → AI suite: duplicates · Note workflows use AI for duplicate detection and suggestions.
- Import svc → AI suite: enhances · Import pipeline uses AI-assisted quality, categorisation, or embeddings.
- Notes tests → Notes svc: verifies · Service tests cover the note domain boundary.
- Import tests → Import svc: verifies · Tests exercise import parsing and transformation behavior.
