# chadroyer/aiworkflowoptimizer architecture

> Architecture diagram of the GitHub repository chadroyer/aiworkflowoptimizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chadroyer/aiworkflowoptimizer
- Repository: https://github.com/chadroyer/aiworkflowoptimizer

## Overview

##### High-Level Architecture Layers
- Client Layer (React SPA)
- Server Layer (Node.js + Express API)
- Data Layer (PostgreSQL + Drizzle ORM)
- External Services (Claude AI, Web Search API)

##### Main Components
A. Frontend (client/)
- React SPA entry (index.html → main.tsx)
- UI component library (shadcn/ui + TailwindCSS)
- Feature modules:
– Authentication (auth-form, login-form, auth-context, use-auth)
– Debug panel (debug-panel)
– Layout & navigation (header, user-profile, protected-route)
- State management via React Contexts (auth-context, chat-context) and React Query (queryClient)
- Pages: auth-page.tsx, chat.tsx, login.tsx, not-found.tsx

B. Backend (server/)
- Express app (index.ts → vite.ts for dev)
- Route definitions (routes.ts)
- Handlers for:
– Authentication (/auth)
– AI calls (/claude.ts)
– Web search (/websearch.ts)
– Storage / file handling (/storage.ts)
– Debugging endpoints (/debug.ts)
- API wiring and middleware

C. Data Layer (db/ + shared/schema.ts)
- Drizzle ORM configuration (drizzle.config.ts)
- Schema definitions (shared/schema.ts)
- Database connector (db/index.ts)
- Seed script (db/seed.ts)

D. External Services
- Anthropic Claude AI (via server/claude.ts)
- Search API (Serper or Google via server/websearch.ts)

E. Developer Tools
- Built-in debug panel (client/src/components/debug)
- Replit agent documentation (replit_agent/*.md)

##### Interactions & Data Flows
- User browser ↔ HTTP(S) ↔ Express API
- Auth requests
- Chat messages → server → Claude → server → client
- AI opportunity suggestions (with optional web search)
- Server ↔ PostgreSQL (Drizzle ORM) for persisting chats, workflows, user data
- Server ↔ Anthropic Claude service (API calls)
- Server ↔ Search API service

##### Architectural Patterns & Principles
- Separation of concerns: UI vs business logic vs data persistence
- SPA communicates with RESTful (or RPC-style) Express API
- Contexts & hooks for client-side state management
- Modular route handlers for AI and search integrations
- Shared code (schema.ts) for DRY database modeling

##### Final Checklist
✔ Four logical layers (Client, Server, Data, External)
✔ Components grouped and labeled by folder or functionality
✔ Callouts for key integrations (Anthropic Claude, Search API)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        Browser["User Browser"]:::external
        HTML["Index HTML Template<br/>(client/index.html)"]:::frontend
        Main["Client Entry Point<br/>(main.tsx)"]:::frontend
        App["React App Component<br/>(App.tsx)"]:::frontend
        subgraph "UI Component Library"
            UI["Shadcn UI + Tailwind CSS<br/>(client/src/components/ui/)"]:::frontend
        end
        subgraph "Authentication Module"
            AuthForm["auth-form.tsx"]:::frontend
            LoginForm["login-form.tsx"]:::frontend
            AuthContext["auth-context.tsx"]:::frontend
            UseAuth["use-auth.ts"]:::frontend
            AuthPage["auth-page.tsx & login.tsx"]:::frontend
        end
        subgraph "Chat & Workflow Module"
            ChatUI["Chat UI Components<br/>(client/src/components/chat/)"]:::frontend
            ChatContext["chat-context.tsx"]:::frontend
            UseChat["use-chat.ts"]:::frontend
            ChatPage["chat.tsx"]:::frontend
        end
        DebugPanel["Debug Panel<br/>(debug-panel.tsx)"]:::devtool
        subgraph "Layout & Navigation"
            Header["header.tsx"]:::frontend
            UserProfile["user-profile.tsx"]:::frontend
            ProtectedRoute["protected-route.tsx"]:::frontend
        end
        subgraph "State Management & API Client"
            QueryClient["queryClient.ts"]:::frontend
            APIUtils["api.ts & auth.ts"]:::frontend
        end
        subgraph "Misc Hooks & Utils"
            UseMobile["use-mobile.tsx"]:::frontend
            UseToast["use-toast.ts"]:::frontend
            Utils["utils.ts"]:::frontend
        end
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        ExpressApp["Express App Entry<br/>(index.ts)"]:::backend
        DevServer["Dev Server Setup<br/>(vite.ts)"]:::backend
        Routes["Route Definitions<br/>(routes.ts)"]:::backend
        subgraph "Handlers"
            AuthAPI["Authentication API<br/>(auth.ts)"]:::backend
            ClaudeAPI["Anthropic Claude<br/>(claude.ts)"]:::backend
            WebSearchAPI["Web Search API<br/>(websearch.ts)"]:::backend
            Storage["File Storage<br/>(storage.ts)"]:::backend
            DebugAPI["Debug Endpoints<br/>(debug.ts)"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DrizzleConfig["Drizzle ORM Config<br/>(drizzle.config.ts)"]:::db
        DBConnector["Database Connector<br/>(db/index.ts)"]:::db
        Schema["Schema Definitions<br/>(shared/schema.ts)"]:::db
        Seed["Seed Script<br/>(db/seed.ts)"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ClaudeService["Anthropic Claude AI"]:::external
        SearchService["Search API (Serper/Google)"]:::external
    end

    %% Interactions
    Browser -->|Loads HTML| HTML
    HTML -->|Bootstraps| Main
    Main -->|Renders| App
    App -->|Uses| UI
    App -->|Routes| AuthPage
    App -->|Routes| ChatPage
    AuthPage -->|Uses| AuthContext
    AuthPage -->|Uses| UseAuth
    AuthContext -->|Provides| AuthForm
    AuthContext -->|Provides| LoginForm
    ChatPage -->|Uses| ChatContext
    ChatPage -->|Uses| UseChat
    ChatContext -->|Provides| ChatUI
    ChatContext -->|Invokes| DebugPanel
    App -->|Uses| Header
    App -->|Uses| UserProfile
    App -->|Guards| ProtectedRoute
    App -->|Configures| QueryClient
    App -->|Calls| APIUtils
    App -->|Uses| UseMobile
    App -->|Uses| UseToast
    App -->|Uses| Utils

    App -->|HTTP/HTTPS REST| ExpressApp
    ExpressApp -->|Uses| Routes
    Routes -->|Calls| AuthAPI
    Routes -->|Calls| ClaudeAPI
    Routes -->|Calls| WebSearchAPI
    Routes -->|Calls| Storage
    Routes -->|Calls| DebugAPI

    ClaudeAPI -->|Anthropic API Calls| ClaudeService
    WebSearchAPI -->|HTTP Requests| SearchService

    ExpressApp -->|Drizzle ORM Queries| DBConnector
    DBConnector -->|Loads Config| DrizzleConfig
    DBConnector -->|Loads Schema| Schema
    DBConnector -->|Seeds Data| Seed

    %% Click Events
    click Main "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/main.tsx"
    click HTML "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/index.html"
    click App "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/App.tsx"
    click UI "https://github.com/chadroyer/aiworkflowoptimizer/tree/main/client/src/components/ui/"
    click AuthForm "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/components/auth/auth-form.tsx"
    click LoginForm "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/components/auth/login-form.tsx"
    click AuthContext "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/contexts/auth-context.tsx"
    click UseAuth "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/hooks/use-auth.ts"
    click AuthPage "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/pages/auth-page.tsx"
    click ChatUI "https://github.com/chadroyer/aiworkflowoptimizer/tree/main/client/src/components/chat/"
    click ChatContext "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/contexts/chat-context.tsx"
    click UseChat "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/hooks/use-chat.ts"
    click ChatPage "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/pages/chat.tsx"
    click DebugPanel "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/components/debug/debug-panel.tsx"
    click Header "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/components/layout/header.tsx"
    click UserProfile "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/components/layout/user-profile.tsx"
    click ProtectedRoute "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/lib/protected-route.tsx"
    click QueryClient "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/lib/queryClient.ts"
    click APIUtils "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/lib/api.ts"
    click APIUtils "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/lib/auth.ts"
    click UseMobile "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/hooks/use-mobile.tsx"
    click UseToast "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/hooks/use-toast.tsx"
    click Utils "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/client/src/lib/utils.ts"
    click ExpressApp "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/server/index.ts"
    click DevServer "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/server/vite.ts"
    click Routes "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/server/routes.ts"
    click AuthAPI "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/server/auth.ts"
    click ClaudeAPI "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/server/claude.ts"
    click WebSearchAPI "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/server/websearch.ts"
    click Storage "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/server/storage.ts"
    click DebugAPI "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/server/debug.ts"
    click DrizzleConfig "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/drizzle.config.ts"
    click DBConnector "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/db/index.ts"
    click Schema "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/shared/schema.ts"
    click Seed "https://github.com/chadroyer/aiworkflowoptimizer/blob/main/db/seed.ts"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#4d8fcc,color:#000
    classDef backend fill:#d4edda,stroke:#5ca36b,color:#000
    classDef db fill:#fff3cd,stroke:#d6a400,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef devtool fill:#f8d7da,stroke:#c82333,color:#000
```
