# ikueisou/morphic architecture

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

- Interactive diagram: https://gitdiagram.com/ikueisou/morphic
- Repository: https://github.com/ikueisou/morphic

## Overview

##### Project type and purpose
- This is a full-stack, AI-powered search engine web application named “Morphic,” built on Next.js App Router and TypeScript. It provides a React-based Generative UI for chat and search, integrates with multiple AI and search providers, and optionally persists chat history in Redis.

##### File structure
- Top-level “app” directory contains Next.js pages and API routes (app/page.tsx, app/api/chat/route.ts, app/api/advanced-search/route.ts).
- “components” holds UI components (chat panels, search sections, shadcn/ui wrappers).
- “lib” contains business logic and services:
- actions (chat orchestration)
- agents (related-questions, researcher)
- tools (question, retrieve, search, video-search)
- streaming (Vercel AI SDK streams)
- redis config
- utils & hooks
- “public/config/models.json” supplies model configurations.
- Dockerfile/docker-compose.yaml for containerized deployment.
- Middleware (middleware.ts) for routing or auth.

##### Additional README insights
- Next.js + React Server Components, Vercel AI SDK streaming, Tailwind CSS + shadcn/ui for styling.
- AI providers via SDK; search providers via HTTP.
- Redis (local or Upstash) for optional chat history.
- Supports SearXNG, Tavily, Exa search engines.

##### Main components & relationships
a. Browser Client (Next.js React pages & RSCs)
b. Next.js Server / Edge Functions (App Router handlers + API Routes)
c. Lib Service Layer
- Agents & Tools: encapsulate search and AI-orchestration logic
- Streaming sub-layer: handles Vercel AI SDK streams
d. Data Store: Redis (Upstash or local)
e. External Services:
- AI Providers (OpenAI, Anthropic, Google AI, etc.)
- Search Providers (Tavily, SearXNG, Exa, Video APIs)
f. Public Assets & Config (models.json, static images)

Interactions:
1) User enters query → Browser Client UI component → invokes API route (/api/chat or /api/advanced-search)
2) API handler pulls in lib/actions which delegate to agents/tools
3) Tools call external search provider(s) over HTTP, then feed to AI via Vercel AI SDK streaming
4) Streaming responses flow back through API to Browser Client
5) If history enabled → lib/redis stores or retrieves chat history

##### Architectural patterns & principles
- Separation of concerns: UI (components) ↔ API Routes ↔ Service layer (lib) ↔ External integrations
- Streaming data flow via Vercel AI SDK (event-driven)
- React Server Components & Edge Functions for low-latency rendering
- Config-driven providers (public/config, .env)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Browser Client (Next.js)" 
        direction TB
        PC["Page: app/page.tsx"] 
        SP["Page: app/search/page.tsx"]
        SIP["Page: app/search/[id]/page.tsx"]
        SHP["Page: app/share/[id]/page.tsx"]
        LYT["Layout: app/layout.tsx"]
        CSS["Styles: app/globals.css"]
        subgraph "UI Components" 
            direction TB
            CPC["components/chat-panel.tsx"]
            CSC["components/search-section.tsx"]
            HLC["components/history-list.tsx"]
            RQC["components/related-questions.tsx"]
            VSC["components/video-search-section.tsx"]
            UIW["components/ui/ (shadcn/ui wrappers)"]
        end
    end

    %% Backend Layer
    subgraph "Next.js Runtime (Backend)" 
        direction TB
        MID["Middleware: middleware.ts"]
        subgraph "API Routes"
            direction TB
            CHAT["Chat API: app/api/chat/route.ts"]
            ADV["Advanced Search API: app/api/advanced-search/route.ts"]
        end
        subgraph "Service Layer (lib)"
            direction TB
            ACT["Actions: lib/actions/chat.ts"]
            subgraph Agents
                direction TB
                ARQ["Related Q: lib/agents/generate-related-questions.ts"]
                AMR["Manual Researcher: lib/agents/manual-researcher.ts"]
                ARR["Researcher: lib/agents/researcher.ts"]
            end
            subgraph Tools
                direction TB
                QT["Question: lib/tools/question.ts"]
                RT["Retrieve: lib/tools/retrieve.ts"]
                ST["Search: lib/tools/search.ts"]
                VT["Video Search: lib/tools/video-search.ts"]
            end
            subgraph Streaming
                direction TB
                CMS["create-manual-tool-stream.ts"]
                CTS["create-tool-calling-stream.ts"]
                HSF["handle-stream-finish.ts"]
                PTC["parse-tool-call.ts"]
                TEX["tool-execution.ts"]
                TYP["types.ts"]
            end
            RED["Redis Config: lib/redis/config.ts"]
            subgraph "Model Config"
                direction TB
                MJS["public/config/models.json"]
                DMJ["lib/config/default-models.json"]
                MTS["lib/config/models.ts"]
            end
        end
        subgraph "Deployment & Env"
            direction TB
            DKF["Dockerfile"]
            DCM["docker-compose.yaml"]
            NCM["next.config.mjs"]
            ENV[".env.local.example"]
        end
        subgraph "Static Assets"
            direction TB
            IMG["public/images/"]
            LOGO["public/providers/logos/"]
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AI["AI Providers"] 
        SPV["Search Providers"]
    end

    %% Data Store
    REDIS["Redis (Data Store)"] 

    %% Connections
    PC -->|"invoke chat"| CHAT
    SP -->|"invoke advancedSearch"| ADV
    CHAT -->|"calls chatStream()"| ACT
    ADV -->|"uses searchResults()"| ST
    ACT -->|"orchestrate()"| ARQ
    ACT -->|"orchestrate()"| AMR
    ACT -->|"orchestrate()"| ARR
    ARQ -->|"callTool()"| QT
    AMR -->|"callTool()"| RT
    ARR -->|"callTool()"| ST
    ARR -->|"callTool()"| VT
    QT -->|"fetchSearchResults()"| SPV
    RT -->|"retrieve()"| SPV
    ST -->|"search()"| SPV
    VT -->|"videoSearch()"| SPV
    SPV -->|"results()"| ST
    ST -->|"streamRequest()"| CMS
    CMS --> CTS
    CTS --> HSF
    HSF --> PTC
    PTC --> TEX
    TEX --> TYP
    TYP -->|"streamResponse()"| CHAT
    CHAT -->|"responseStream()"| PC
    CHAT -->|"saveHistory() / getHistory()"| REDIS
    ADV -->|"getHistory()"| REDIS

    %% Click Events
    click PC "https://github.com/ikueisou/morphic/blob/main/app/page.tsx"
    click SP "https://github.com/ikueisou/morphic/blob/main/app/search/page.tsx"
    click SIP "https://github.com/ikueisou/morphic/blob/main/app/search/[id]/page.tsx"
    click SHP "https://github.com/ikueisou/morphic/blob/main/app/share/[id]/page.tsx"
    click LYT "https://github.com/ikueisou/morphic/blob/main/app/layout.tsx"
    click CSS "https://github.com/ikueisou/morphic/blob/main/app/globals.css"
    click CPC "https://github.com/ikueisou/morphic/blob/main/components/chat-panel.tsx"
    click CSC "https://github.com/ikueisou/morphic/blob/main/components/search-section.tsx"
    click HLC "https://github.com/ikueisou/morphic/blob/main/components/history-list.tsx"
    click RQC "https://github.com/ikueisou/morphic/blob/main/components/related-questions.tsx"
    click VSC "https://github.com/ikueisou/morphic/blob/main/components/video-search-section.tsx"
    click UIW "https://github.com/ikueisou/morphic/tree/main/components/ui/"
    click CHAT "https://github.com/ikueisou/morphic/blob/main/app/api/chat/route.ts"
    click ADV "https://github.com/ikueisou/morphic/blob/main/app/api/advanced-search/route.ts"
    click ACT "https://github.com/ikueisou/morphic/blob/main/lib/actions/chat.ts"
    click ARQ "https://github.com/ikueisou/morphic/blob/main/lib/agents/generate-related-questions.ts"
    click AMR "https://github.com/ikueisou/morphic/blob/main/lib/agents/manual-researcher.ts"
    click ARR "https://github.com/ikueisou/morphic/blob/main/lib/agents/researcher.ts"
    click QT "https://github.com/ikueisou/morphic/blob/main/lib/tools/question.ts"
    click RT "https://github.com/ikueisou/morphic/blob/main/lib/tools/retrieve.ts"
    click ST "https://github.com/ikueisou/morphic/blob/main/lib/tools/search.ts"
    click VT "https://github.com/ikueisou/morphic/blob/main/lib/tools/video-search.ts"
    click CMS "https://github.com/ikueisou/morphic/blob/main/lib/streaming/create-manual-tool-stream.ts"
    click CTS "https://github.com/ikueisou/morphic/blob/main/lib/streaming/create-tool-calling-stream.ts"
    click HSF "https://github.com/ikueisou/morphic/blob/main/lib/streaming/handle-stream-finish.ts"
    click PTC "https://github.com/ikueisou/morphic/blob/main/lib/streaming/parse-tool-call.ts"
    click TEX "https://github.com/ikueisou/morphic/blob/main/lib/streaming/tool-execution.ts"
    click TYP "https://github.com/ikueisou/morphic/blob/main/lib/streaming/types.ts"
    click RED "https://github.com/ikueisou/morphic/blob/main/lib/redis/config.ts"
    click MJS "https://github.com/ikueisou/morphic/blob/main/public/config/models.json"
    click DMJ "https://github.com/ikueisou/morphic/blob/main/lib/config/default-models.json"
    click MTS "https://github.com/ikueisou/morphic/blob/main/lib/config/models.ts"
    click MID "https://github.com/ikueisou/morphic/blob/main/middleware.ts"
    click DKF "https://github.com/ikueisou/morphic/tree/main/Dockerfile"
    click DCM "https://github.com/ikueisou/morphic/blob/main/docker-compose.yaml"
    click NCM "https://github.com/ikueisou/morphic/blob/main/next.config.mjs"
    click ENV "https://github.com/ikueisou/morphic/blob/main/.env.local.example"
    click IMG "https://github.com/ikueisou/morphic/tree/main/public/images/"
    click LOGO "https://github.com/ikueisou/morphic/tree/main/public/providers/logos/"

    %% Styles
    classDef frontend fill:#e0f7e9,stroke:#2e7d32,stroke-width:2px
    classDef backend fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef datastore fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef external fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px

    class PC,SP,SIP,SHP,LYT,CSS,CPC,CSC,HLC,RQC,VSC,UIW frontend
    class MID,CHAT,ADV,ACT,ARQ,AMR,ARR,QT,RT,ST,VT,CMS,CTS,HSF,PTC,TEX,TYP backend
    class REDIS datastore
    class AI,SPV external
```
