# superexpert/superexpert-ai architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source, full-stack Next.js application (“Superexpert.AI”) for building and managing AI agents without coding.
- The README describes a web platform with an admin UI for configuring agents and a chat UI for interacting with deployed agents.

##### File structure
- app/ (Next.js App Router)
- (admin)/… — Admin-side pages, layout, API routes under app/(admin)/api
- (chat)/… — Chat-side pages, layout, API routes under app/(chat)/[agentName]/api/ai
- ui/ — Shared React components for both admin and chat
- lib/ — Core business logic, database services (Prisma), adapters for LLMs & embeddings, task engines, session/auth services
- prisma/ — Database schema (PostgreSQL/MySQL)
- rag-strategies/ — Retrieval-augmented generation strategies
- tools/ & scripts/ — Helper utilities & maintenance scripts
- Configuration & infra: next.config.ts, vercel.json, superexpert-ai.config.ts

##### README for additional insights
- Emphasis on no-code agent creation, multi-task AI agents, monitoring and logging

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client
    Browser["User Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        AdminUI["Next.js Admin UI"]:::frontend
        ChatUI["Next.js Chat UI"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        Middleware["middleware.ts"]:::api
        AdminAPI["Admin API Routes"]:::api
        ChatAPI["Chat API Route"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        direction TB
        AdminActions["lib/actions/admin-actions.ts"]:::service
        ServerActions["lib/actions/server-actions.ts"]:::service
        DBService["lib/db/db-service.ts"]:::service
        DBAdminService["lib/db/db-admin-service.ts"]:::service
        PrismaClient["lib/db/prisma.ts"]:::service
        Agent["lib/agent.ts"]:::service
        TaskDef["lib/task-definition.ts"]:::service
        TaskMachine["lib/task-machine.ts"]:::service
        Corpus["lib/corpus.ts"]:::service
        CorpusFile["lib/corpus-file.ts"]:::service
        CorpusQuery["lib/corpus-query.ts"]:::service
        OpenAIAdapter["lib/adapters/llm-adapters/openai-llm-adapter.ts"]:::service
        AnthropicAdapter["lib/adapters/llm-adapters/anthropic-llm-adapter.ts"]:::service
        GoogleAdapter["lib/adapters/llm-adapters/google-llm-adapter.ts"]:::service
        Factory["lib/adapters/llm-adapters/llm-model-factory.ts"]:::service
        EmbedAdapter["lib/adapters/embedding-adapters/openai-embedding-adapter.ts"]:::service
        KeywordStrategy["rag-strategies/keyword-strategy.ts"]:::service
        SemanticStrategy["rag-strategies/semantic-strategy.ts"]:::service
        StrategyRegistry["rag-strategies/rag-strategies.ts"]:::service
        SessionStorage["lib/session-storage.ts"]:::service
        AuthConfig["auth.config.ts"]:::service
        Logger["lib/logger.ts"]:::service
    end

    %% Persistence Layer
    Database["Prisma DB (PostgreSQL)"]:::storage
    SchemaPrisma["prisma/schema.prisma"]:::storage

    %% External Services
    subgraph "External AI Services"
        direction TB
        LLMs["LLM Providers (OpenAI, Anthropic, Google)"]:::external
        EmbeddingService["Embedding Service"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        NextConfig["next.config.ts"]:::infra
        VercelConfig["vercel.json"]:::infra
        ProjectConfig["superexpert-ai.config.ts"]:::infra
    end

    %% Connections
    Browser -->|"interacts with"| AdminUI
    Browser -->|"interacts with"| ChatUI

    AdminUI -->|"calls API"| AdminAPI
    ChatUI -->|"POST /api/ai"| ChatAPI

    AdminAPI -->|“uses”| Middleware
    ChatAPI -->|“uses”| Middleware

    Middleware -->|"invokes"| AdminActions
    Middleware -->|"invokes"| ServerActions

    AdminActions -->|"queries"| DBAdminService
    ServerActions -->|"queries"| DBService
    DBAdminService -->|"uses Prisma"| PrismaClient
    DBService -->|"uses Prisma"| PrismaClient
    PrismaClient -->|"executes on"| Database
    PrismaClient -->|"reads schema"| SchemaPrisma

    Agent -->|"manages tasks"| TaskMachine
    TaskMachine -->|"defines"| TaskDef
    Agent -->|"stores metadata"| DBService

    CorpusQuery -->|"accesses"| Corpus
    CorpusQuery -->|"handles files"| CorpusFile
    Corpus -->|"persists"| Database

    StrategyRegistry -->|"registers"| KeywordStrategy
    StrategyRegistry -->|"registers"| SemanticStrategy
    KeywordStrategy -->|"calls"| EmbedAdapter
    SemanticStrategy -->|"calls"| EmbedAdapter
    EmbedAdapter -->|"embeds via"| EmbeddingService
    Factory -->|"selects adapter"| OpenAIAdapter
    Factory -->|"selects adapter"| AnthropicAdapter
    Factory -->|"selects adapter"| GoogleAdapter
    OpenAIAdapter -->|"calls"| LLMs
    AnthropicAdapter -->|"calls"| LLMs
    GoogleAdapter -->|"calls"| LLMs

    SessionStorage -->|"stores sessions"| Database
    AuthConfig -->|"configures"| Middleware
    Logger -->|"logs to"| AdminAPI
    Logger -->|"logs to"| Database

    %% Infra connections
    AdminUI -->|"deployed on"| VercelConfig
    ChatUI -->|"deployed on"| VercelConfig
    AdminAPI -->|"runs on"| VercelConfig
    ChatAPI -->|"runs on"| VercelConfig
    NextConfig -->|"configures"| AdminUI
    NextConfig -->|"configures"| ChatUI

    %% Click Events
    click AdminUI "https://github.com/superexpert/superexpert-ai/tree/main/app/(admin)/"
    click ChatUI "https://github.com/superexpert/superexpert-ai/tree/main/app/(chat)/"
    click AdminAPI "https://github.com/superexpert/superexpert-ai/blob/main/app/(admin)/api/logs/stream/route.ts"
    click ChatAPI "https://github.com/superexpert/superexpert-ai/blob/main/app/(chat)/[agentName]/api/ai/route.ts"
    click AdminActions "https://github.com/superexpert/superexpert-ai/blob/main/lib/actions/admin-actions.ts"
    click ServerActions "https://github.com/superexpert/superexpert-ai/blob/main/lib/actions/server-actions.ts"
    click DBService "https://github.com/superexpert/superexpert-ai/blob/main/lib/db/db-service.ts"
    click DBAdminService "https://github.com/superexpert/superexpert-ai/blob/main/lib/db/db-admin-service.ts"
    click PrismaClient "https://github.com/superexpert/superexpert-ai/blob/main/lib/db/prisma.ts"
    click Agent "https://github.com/superexpert/superexpert-ai/blob/main/lib/agent.ts"
    click TaskDef "https://github.com/superexpert/superexpert-ai/blob/main/lib/task-definition.ts"
    click TaskMachine "https://github.com/superexpert/superexpert-ai/blob/main/lib/task-machine.ts"
    click Corpus "https://github.com/superexpert/superexpert-ai/blob/main/lib/corpus.ts"
    click CorpusFile "https://github.com/superexpert/superexpert-ai/blob/main/lib/corpus-file.ts"
    click CorpusQuery "https://github.com/superexpert/superexpert-ai/blob/main/lib/corpus-query.ts"
    click OpenAIAdapter "https://github.com/superexpert/superexpert-ai/blob/main/lib/adapters/llm-adapters/openai-llm-adapter.ts"
    click AnthropicAdapter "https://github.com/superexpert/superexpert-ai/blob/main/lib/adapters/llm-adapters/anthropic-llm-adapter.ts"
    click GoogleAdapter "https://github.com/superexpert/superexpert-ai/blob/main/lib/adapters/llm-adapters/google-llm-adapter.ts"
    click Factory "https://github.com/superexpert/superexpert-ai/blob/main/lib/adapters/llm-adapters/llm-model-factory.ts"
    click EmbedAdapter "https://github.com/superexpert/superexpert-ai/blob/main/lib/adapters/embedding-adapters/openai-embedding-adapter.ts"
    click KeywordStrategy "https://github.com/superexpert/superexpert-ai/blob/main/rag-strategies/keyword-strategy.ts"
    click SemanticStrategy "https://github.com/superexpert/superexpert-ai/blob/main/rag-strategies/semantic-strategy.ts"
    click StrategyRegistry "https://github.com/superexpert/superexpert-ai/blob/main/rag-strategies/rag-strategies.ts"
    click SessionStorage "https://github.com/superexpert/superexpert-ai/blob/main/lib/session-storage.ts"
    click AuthConfig "https://github.com/superexpert/superexpert-ai/blob/main/auth.config.ts"
    click Logger "https://github.com/superexpert/superexpert-ai/blob/main/lib/logger.ts"
    click Middleware "https://github.com/superexpert/superexpert-ai/blob/main/middleware.ts"
    click SchemaPrisma "https://github.com/superexpert/superexpert-ai/blob/main/prisma/schema.prisma"
    click NextConfig "https://github.com/superexpert/superexpert-ai/blob/main/next.config.ts"
    click VercelConfig "https://github.com/superexpert/superexpert-ai/blob/main/vercel.json"
    click ProjectConfig "https://github.com/superexpert/superexpert-ai/blob/main/superexpert-ai.config.ts"

    %% Styles
    classDef frontend fill:#e0f7e9,stroke:#2dca73,stroke-width:1px
    classDef api fill:#e3f2fd,stroke:#42a5f5,stroke-width:1px
    classDef service fill:#f1f8e9,stroke:#7cb342,stroke-width:1px
    classDef storage fill:#f3e5f5,stroke:#ab47bc,stroke-width:1px
    classDef external fill:#fff3e0,stroke:#fb8c00,stroke-width:1px
    classDef infra fill:#eceff1,stroke:#607d8b,stroke-width:1px
```
