How amritkaur15/gather works
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: AppShell.tsx App shell · chat.ts AI suite · notes/service.ts Notes svc · import/service.ts Import svc
Components 24
App routes
Public, auth, and workspace route boundaries.
API routes
Next.js route handlers organized by domain.
- Notes API · CRUD, archive, merge, search, formatting, duplicate checks.
src/app/api/notes - Catalog API · Collections and tags membership and CRUD endpoints.
src/app/api/collections - Import API · Import preview, jobs, and PDF direct ingest.
src/app/api/import - AI API · Categorisation and chat endpoints.
src/app/api/ai - Auth API · NextAuth session and registration endpoints.
src/app/api/auth
UI components
Client-side workspace, editor, auth, and feature panels.
- App shell · Main layout coordinating sidebar, list, and editor.
src/components/layout/AppShell.tsx - Editor · Tiptap-based note editor and toolbar.
src/components/editor/TiptapEditor.tsx - Sidebar · Collection and workspace navigation.
src/components/layout/Sidebar.tsx - Note list · Browse and select notes.
src/components/layout/NoteList.tsx - Feature panels · AI, import, duplicate, and context UI surfaces.
src/components/ai/AIChatPanel.tsx - Session · Client session provider for authenticated UI.
src/components/SessionProvider.tsx
Domain libs
Business logic, AI, import, auth, and persistence helpers.
- Notes svc · Note lifecycle, formatting, archive, merge, duplicate logic.
src/lib/notes/service.ts - Catalog svc · Collections and tags business rules.
src/lib/collections/service.ts - Import svc · Import orchestration, parsing, processing, and Tiptap conversion.
src/lib/import/service.ts - AI suite · Categorise, chat, embeddings, search, duplicates, and suggestions.
src/lib/ai/chat.ts - Auth config · Server auth strategy and session configuration.
src/lib/auth/config.ts
Data layer
Database client and schema/migrations.
- Database · Database client and schema definitions.
src/lib/db/schema.ts - Migrations · Drizzle migration history including search indexing.
drizzle/migrations
Tests
Service-oriented verification mirroring production boundaries.
- Notes tests · Verification for note domain behavior.
tests/lib/notes/service.test.ts - Import tests · Verification for parsing and transformation pipeline.
tests/lib/import/service.test.ts
Connections 28
- 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.