# devmehrab/outreach-ai architecture

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

- Interactive diagram: https://gitdiagram.com/devmehrab/outreach-ai
- Repository: https://github.com/devmehrab/outreach-ai

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** application with a clear split between **server-side route handlers** under `app/api`, **page routes** under `app/`, and reusable **feature components** under `components/`.
   - The repo is organized around three main product areas: **lists**, **templates**, and a **tool/editor** workflow.

2. **Primary user-facing routes**
   - `app/page.js` is the landing page.
   - `app/login/page.jsx` and `app/register/page.jsx` handle authentication entry points.
   - The main authenticated area lives under `app/(main)/...`, with pages for:
     - `list` and `list/[id]`
     - `templates`
     - `settings`
     - `tool`
   - `app/(main)/layout.js` likely provides the shared authenticated shell, such as navigation/sidebar and layout framing.

3. **Core domain boundaries**
   - The app’s data model is centered on:
     - `models/List.js`
     - `models/Template.js`
     - `models/User.js`
   - These models indicate three persistent domains: user accounts, reusable templates, and user-owned lists.
   - The `list` domain also has sub-views for table/editing and upload/manual creation flows, suggesting list creation and list item management are major interactions.

4. **API layer as the server boundary**
   - Business operations are exposed through route handlers in `app/api/...`.
   - There are dedicated endpoints for:
     - authentication: `login`, `logout`, `register`, `me`
     - templates: `templates` and `templates/[id]`
     - lists: `lists` and `lists/[id]`
     - generation: `generate`
   - This means the frontend mostly talks to the backend through HTTP API calls rather than direct server actions.

5. **Data and persistence**
   - `lib/db.js` and the model files strongly suggest a database-backed app, likely using a MongoDB-style persistence layer.
   - `lib/storage.js` indicates additional storage concerns beyond normal DB records, likely for uploaded files or derived artifacts.
   - The list upload UI and generation flow suggest data can enter the system both manually and through uploaded content.

6. **Authentication and access control**
   - Auth is handled in `app/api/login`, `app/api/logout`, `app/api/register`, and `app/api/me`.
   - `lib/auth.js` and `middleware.js` form the security boundary: middleware likely protects authenticated routes and redirects unauthenticated users.
   - `components/tool/providers/AuthProvider.jsx` suggests the frontend also keeps auth state available to the tool/editor subtree.

7. **Template-driven generation flow**
   - The `tool` area and `app/api/generate/route.js` point to a workflow where a user inputs content, selects or edits a template, and receives generated output.
   - Supporting pieces include:
     - `components/editor/TemplateEditor.jsx`
     - `components/editor/GeneratedOutput.jsx`
     - `components/inputs/DynamicInputs.jsx`
     - `lib/placeholder.js`, `lib/replace.js`, and `constants/placeholderRegex.js`
   - This implies a pipeline of **template + placeholders + input data → generated text/output**.

8. **Lists UI and interaction model**
   - The list feature is decomposed into presentation and editing pieces:
     - `ListView`, `ListTable`, `ListCard`, `ListViewHeader`
     - `CreateListForm`, `EditableRow`
     - `ManualTab`, `UploadTab`
     - `DeleteConfirmationModal`
   - Hooks like `hooks/useLists.js` likely encapsulate fetching, mutations, and local UI state for list operations.
   - `components/shared/PaginationControls.jsx` suggests list browsing is paginated.

9. **Templates UI**
   - Templates have their own CRUD-oriented UI surface:
     - `components/template/TemplateCard.jsx`
     - `components/template/Header.jsx`
     - `components/template/SaveTemplateModal.jsx`
   - `hooks/useTemplates.js` likely handles fetching and mutating templates from the API.
   - This area appears to be the reusable content library that feeds the generation tool and possibly list workflows.

10. **Shared frontend infrastructure**
   - `components/ui/*` contains the base design-system primitives, likely generated from or inspired by shadcn/ui.
   - `components/providers/ToasterProvider.jsx` indicates global toast/notification handling.
   - `components/shared/Sidebar.jsx`, plus `app/(main)/layout.js`, define the authenticated shell used across the main app sections.
   - `hooks/useClipboard.js` and `lib/clipboard.js` support copy/export-like interactions in the tool/editor flow.

11. **Rendering and loading states**
   - The `tool` route has dedicated `loading.jsx` and `error.jsx`, so the generation/editor workflow has explicit async and failure handling.
   - This suggests the tool depends on server calls or data hydration that can fail independently of the rest of the app.
   - `components/ui/skeleton.jsx` and similar primitives are likely used to smooth loading states across feature pages.

12. **Static assets and product positioning**
   - `public/images/*` contains product imagery for hero, AI, upload, list, and send concepts.
   - Combined with the route structure, the app looks like a product for **building templates, processing lists, and generating output from structured input**, rather than a generic CRUD dashboard.

Main entry points: [`app/(main)/layout.js`](https://github.com/devmehrab/outreach-ai/blob/main/app/(main)/layout.js) (Main shell), [`components/tool/ToolContent.jsx`](https://github.com/devmehrab/outreach-ai/blob/main/components/tool/ToolContent.jsx) (Tool UI), [`lib/db.js`](https://github.com/devmehrab/outreach-ai/blob/main/lib/db.js) (Core libs), [`hooks/useLists.js`](https://github.com/devmehrab/outreach-ai/blob/main/hooks/useLists.js) (Feature hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routes["App routes"]
  node_app_home["Landing<br/>page route<br/>[page.js]"]
  node_app_login["Login<br/>auth page<br/>[page.jsx]"]
  node_app_register["Register<br/>auth page<br/>[page.jsx]"]
  node_main_layout["Main shell<br/>app shell<br/>[layout.js]"]
  node_list_pages["Lists area<br/>list pages<br/>[page.jsx]"]
  node_templates_page["Templates<br/>main page<br/>[page.jsx]"]
  node_settings_page["Settings<br/>main page<br/>[page.jsx]"]
  node_tool_page["Tool<br/>editor page<br/>[page.jsx]"]
end

subgraph group_api["API routes"]
  node_auth_api[("Auth API<br/>route handlers<br/>[route.js]")]
  node_list_api[("Lists API<br/>route handlers<br/>[route.js]")]
  node_template_api[("Templates API<br/>route handlers<br/>[route.js]")]
  node_generate_api[("Generate API<br/>route handler<br/>[route.js]")]
end

subgraph group_features["Feature UI"]
  node_list_ui["List UI<br/>feature set<br/>[ListView.jsx]"]
  node_template_ui["Template UI<br/>feature set<br/>[TemplateCard.jsx]"]
  node_tool_ui["Tool UI<br/>editor flow<br/>[ToolContent.jsx]"]
  node_ui_primitives["UI primitives<br/>design system<br/>[button.jsx]"]
end

subgraph group_infra["App infra"]
  node_hooks_state(("Feature hooks<br/>client state<br/>[useLists.js]"))
  node_models_data[("Data models<br/>domain models<br/>[List.js]")]
  node_core_lib{{"Core libs<br/>server helpers<br/>[db.js]"}}
  node_placeholder_consts["Placeholder rules<br/>constants"]
end

node_app_home -->|"renders under"| node_main_layout
node_app_login -->|"auth calls"| node_auth_api
node_app_register -->|"auth calls"| node_auth_api
node_main_layout -->|"hosts"| node_list_pages
node_main_layout -->|"hosts"| node_templates_page
node_main_layout -->|"hosts"| node_settings_page
node_main_layout -->|"hosts"| node_tool_page
node_main_layout -->|"composes"| node_ui_primitives
node_list_pages -->|"uses"| node_list_ui
node_templates_page -->|"uses"| node_template_ui
node_tool_page -->|"uses"| node_tool_ui
node_tool_ui -->|"calls"| node_generate_api
node_tool_ui -->|"depends on"| node_template_ui
node_tool_ui -->|"composes"| node_ui_primitives
node_list_ui -->|"calls"| node_list_api
node_template_ui -->|"calls"| node_template_api
node_auth_api -->|"uses"| node_core_lib
node_list_api -->|"persists"| node_models_data
node_template_api -->|"persists"| node_models_data
node_generate_api -->|"uses"| node_core_lib
node_hooks_state -->|"fetches"| node_list_api
node_hooks_state -->|"fetches"| node_template_api
node_hooks_state -->|"uses"| node_core_lib
node_placeholder_consts -->|"supports"| node_core_lib

click node_app_home "https://github.com/devmehrab/outreach-ai/blob/main/app/page.js"
click node_app_login "https://github.com/devmehrab/outreach-ai/blob/main/app/login/page.jsx"
click node_app_register "https://github.com/devmehrab/outreach-ai/blob/main/app/register/page.jsx"
click node_main_layout "https://github.com/devmehrab/outreach-ai/blob/main/app/(main)/layout.js"
click node_list_pages "https://github.com/devmehrab/outreach-ai/blob/main/app/(main)/list/page.jsx"
click node_templates_page "https://github.com/devmehrab/outreach-ai/blob/main/app/(main)/templates/page.jsx"
click node_settings_page "https://github.com/devmehrab/outreach-ai/blob/main/app/(main)/settings/page.jsx"
click node_tool_page "https://github.com/devmehrab/outreach-ai/blob/main/app/(main)/tool/page.jsx"
click node_auth_api "https://github.com/devmehrab/outreach-ai/blob/main/app/api/login/route.js"
click node_list_api "https://github.com/devmehrab/outreach-ai/blob/main/app/api/lists/route.js"
click node_template_api "https://github.com/devmehrab/outreach-ai/blob/main/app/api/templates/route.js"
click node_generate_api "https://github.com/devmehrab/outreach-ai/blob/main/app/api/generate/route.js"
click node_list_ui "https://github.com/devmehrab/outreach-ai/blob/main/components/list/ListView.jsx"
click node_template_ui "https://github.com/devmehrab/outreach-ai/blob/main/components/template/TemplateCard.jsx"
click node_tool_ui "https://github.com/devmehrab/outreach-ai/blob/main/components/tool/ToolContent.jsx"
click node_ui_primitives "https://github.com/devmehrab/outreach-ai/blob/main/components/ui/button.jsx"
click node_hooks_state "https://github.com/devmehrab/outreach-ai/blob/main/hooks/useLists.js"
click node_models_data "https://github.com/devmehrab/outreach-ai/blob/main/models/List.js"
click node_core_lib "https://github.com/devmehrab/outreach-ai/blob/main/lib/db.js"
click node_placeholder_consts "https://github.com/devmehrab/outreach-ai/blob/main/constants/placeholderRegex.js"

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_home,node_app_login,node_app_register,node_main_layout,node_list_pages,node_templates_page,node_settings_page,node_tool_page toneBlue
class node_auth_api,node_list_api,node_template_api,node_generate_api toneAmber
class node_list_ui,node_template_ui,node_tool_ui,node_ui_primitives toneMint
class node_hooks_state,node_models_data,node_core_lib,node_placeholder_consts toneRose
```

## Components

### App routes

Next.js page routes and authenticated app shell

- [Landing](https://github.com/devmehrab/outreach-ai/blob/main/app/page.js): page route · Public marketing or entry page · `app/page.js`
- [Login](https://github.com/devmehrab/outreach-ai/blob/main/app/login/page.jsx): auth page · Sign-in entry point · `app/login/page.jsx`
- [Register](https://github.com/devmehrab/outreach-ai/blob/main/app/register/page.jsx): auth page · Account creation entry point · `app/register/page.jsx`
- [Main shell](https://github.com/devmehrab/outreach-ai/blob/main/app/(main)/layout.js): app shell · Authenticated layout shared across main routes · `app/(main)/layout.js`
- [Lists area](https://github.com/devmehrab/outreach-ai/blob/main/app/(main)/list/page.jsx): list pages · List overview and detail routes · `app/(main)/list/page.jsx`
- [Templates](https://github.com/devmehrab/outreach-ai/blob/main/app/(main)/templates/page.jsx): main page · Template management route · `app/(main)/templates/page.jsx`
- [Settings](https://github.com/devmehrab/outreach-ai/blob/main/app/(main)/settings/page.jsx): main page · User settings route · `app/(main)/settings/page.jsx`
- [Tool](https://github.com/devmehrab/outreach-ai/blob/main/app/(main)/tool/page.jsx): editor page · Template-driven generation workspace · `app/(main)/tool/page.jsx`

### API routes

Server-side HTTP boundary for auth, lists, templates, and generation

- [Auth API](https://github.com/devmehrab/outreach-ai/blob/main/app/api/login/route.js): route handlers · Login, logout, register, and session lookup endpoints · `app/api/login/route.js`
- [Lists API](https://github.com/devmehrab/outreach-ai/blob/main/app/api/lists/route.js): route handlers · List collection and item endpoints · `app/api/lists/route.js`
- [Templates API](https://github.com/devmehrab/outreach-ai/blob/main/app/api/templates/route.js): route handlers · Template collection and item endpoints · `app/api/templates/route.js`
- [Generate API](https://github.com/devmehrab/outreach-ai/blob/main/app/api/generate/route.js): route handler · Generation endpoint for tool output · `app/api/generate/route.js`

### Feature UI

Reusable feature components for lists, templates, and tool/editor

- [List UI](https://github.com/devmehrab/outreach-ai/blob/main/components/list/ListView.jsx): feature set · List browsing, creation, editing, upload, and deletion views · `components/list/ListView.jsx`
- [Template UI](https://github.com/devmehrab/outreach-ai/blob/main/components/template/TemplateCard.jsx): feature set · Template cards, headers, and save flow · `components/template/TemplateCard.jsx`
- [Tool UI](https://github.com/devmehrab/outreach-ai/blob/main/components/tool/ToolContent.jsx): editor flow · Editor, preview, output, and auth-aware tool content · `components/tool/ToolContent.jsx`
- [UI primitives](https://github.com/devmehrab/outreach-ai/blob/main/components/ui/button.jsx): design system · Shared base components used across the app · `components/ui/button.jsx`

### App infra

Shared libraries, state hooks, models, and cross-cutting utilities

- [Feature hooks](https://github.com/devmehrab/outreach-ai/blob/main/hooks/useLists.js): client state · Client hooks for fetching and mutating lists, templates, placeholders, and clipboard data · `hooks/useLists.js`
- [Data models](https://github.com/devmehrab/outreach-ai/blob/main/models/List.js): domain models · Persistent user, list, and template models · `models/List.js`
- [Core libs](https://github.com/devmehrab/outreach-ai/blob/main/lib/db.js): server helpers · Auth, DB, storage, placeholder replacement, and utility helpers · `lib/db.js`
- [Placeholder rules](https://github.com/devmehrab/outreach-ai/blob/main/constants/placeholderRegex.js): constants · Regex and placeholder parsing rules for template replacement · `constants/placeholderRegex.js`

## Connections

- Landing → Main shell: renders under · Public app entry shares the root layout
- Login → Auth API: auth calls · Login page submits credentials to auth endpoints
- Register → Auth API: auth calls · Registration page creates accounts through auth endpoints
- Main shell → Lists area: hosts · Authenticated shell frames the list area
- Main shell → Templates: hosts · Authenticated shell frames template management
- Main shell → Settings: hosts · Authenticated shell frames settings
- Main shell → Tool: hosts · Authenticated shell frames the tool workspace
- Main shell → UI primitives: composes · Shared shell uses common UI building blocks
- Lists area → List UI: uses · List routes render the list feature components
- Templates → Template UI: uses · Template route renders template management UI
- Tool → Tool UI: uses · Tool route renders the editor workflow components
- Tool UI → Generate API: calls · Tool workflow requests generated output
- Tool UI → Template UI: depends on · Tool workflow is driven by template selection and editing
- Tool UI → UI primitives: composes · Editor surface uses shared UI controls
- List UI → Lists API: calls · List CRUD and upload flows hit the lists API
- Template UI → Templates API: calls · Template CRUD hits the templates API
- Auth API → Core libs: uses · Auth endpoints rely on shared auth and persistence helpers
- Lists API → Data models: persists · Lists API reads and writes list records
- Templates API → Data models: persists · Templates API reads and writes template records
- Generate API → Core libs: uses · Generation endpoint uses replacement and storage helpers
- Feature hooks → Lists API: fetches · List hook wraps list API access
- Feature hooks → Templates API: fetches · Template hook wraps template API access
- Feature hooks → Core libs: uses · Shared hooks rely on clipboard and placeholder helpers
- Placeholder rules → Core libs: supports · Placeholder parsing rules feed replacement logic