# 0-cyberdyne-systems-0/wordplay architecture

> Architecture diagram of the GitHub repository 0-cyberdyne-systems-0/wordplay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0-cyberdyne-systems-0/wordplay
- Repository: https://github.com/0-cyberdyne-systems-0/wordplay

## Overview

##### Project type and purpose
- From the README and file tree, this is a full-stack AI-powered writing companion called **wordPlay**.
- Frontend: React + TypeScript + Vite + Tailwind.
- Backend: Node.js + Express + Drizzle ORM + PostgreSQL.
- Core functionality: a multi-tool AI agent (19 tools) for research, writing, text analysis, plus slash-commands, web search, and analytics.

##### File structure
- Top-level directories:
- **client/** houses all UI code (pages, components, hooks, providers, UI primitives).
- **server/** contains the Express API, AI-agent orchestration (ai-agent.ts), database interfaces, route definitions, file operations, slash-command logic, and web-search integration.
- **shared/** holds cross-cutting types/schema used by both front and back.
- **migrations/** + **drizzle.config.ts** + **scripts/** manage database schema and initialization.
- **test-*.js** files implement agent and integration tests.
- Key config/build files:
- **package.json**, **tsconfig.json**, **vite.config.ts**, **postcss.config.js**, **tailwind.config.ts**.
- Architectural patterns:
- MVC-style API (routes → controllers in server/… → db/storage).
- Component-driven UI.
- “Provider” pattern for React context.
- Shared code for types & schemas.

##### README for additional insights
React Frontend → Express API → AI Agent Engine → {OpenAI API, Ollama Local, Web Search} + → PostgreSQL.
- Features emphasize real-time analytics, rich text editor, context panel, slash-commands, multi-step reasoning.

##### Elements
- UI components in blue.
- API / services in green.
- External in orange.
- Database in brown.
- **Annotations**: list major frameworks or libraries next to each component (e.g., “React + Vite”).

##### Final advice
- **shared modules** (shared/schema.ts) bridging front and back.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Browser
    User["User / Browser"]:::external

    %% Frontend Layer
    subgraph "React Frontend (client/src)" 
        direction TB
        Editor["Editor Component"]:::ui
        Sidebar["Sidebar Component"]:::ui
        ContextPanel["Context Panel Component"]:::ui
        SlashMenu["Slash-Command Menu Component"]:::ui
        SettingsPanel["Settings Panel Component"]:::ui
        WebSearchUI["Web Search UI Component"]:::ui
        UIPrimitives["UI Primitives Library"]:::ui
        QueryClient["React Query Client"]:::state
        SettingsProv["Settings Provider"]:::state
        ThemeProv["Theme Provider"]:::state
        AIIndicator["AI Agent UI Indicator"]:::ui
    end

    %% Shared Module
    SharedSchema["Shared Schema & Types"]:::shared

    %% Backend API Layer
    subgraph "Express API (server)"
        direction TB
        APIIndex["Express API Entry Point"]:::api
        Routes["API Routes Definition"]:::api
        Controllers["Controllers & Services"]:::api
        subgraph "Controllers & Services"
            direction TB
            AIAgentCtrl["AI Agent Engine Orchestration"]:::api
            SlashCtrl["Slash-Command Logic Controller"]:::api
            WebSearchCtrl["Web-Search Integration Module"]:::api
            OpenAICtrl["OpenAI Integration Module"]:::api
            FileOps["File Operations (attachments)"]:::api
            DBConn["Database Connection & Helpers"]:::api
            DBStorage["Database Storage Abstraction"]:::api
        end
    end

    %% AI Agent Engine Layer
    subgraph "AI Agent Engine"
        direction TB
        AgentCore["Agent Core & Tool Registry"]:::engine
        Pipeline["Multi-step Pipeline"]:::engine
        DocFlow["LLM_PIPELINE_FLOW.md"]:::doc
    end

    %% External Services
    OpenAI["OpenAI API"]:::external
    Ollama["Ollama (Local LLM)"]:::external
    WebSearchExt["Web Search Service"]:::external

    %% Database and Migrations
    Postgres["PostgreSQL (Drizzle ORM)"]:::db
    Migrations["Migration Scripts (migrations/)"]:::db
    DBConfig["Database Configuration"]:::db
    DBMigrate["Migration Runner"]:::db

    %% Tests
    Tests["Agent & Integration Tests"]:::test

    %% Connections
    User -->|interacts with| Editor
    User --> Sidebar
    User --> ContextPanel
    User --> SlashMenu
    User --> SettingsPanel
    User --> WebSearchUI
    Editor -->|uses| UIPrimitives
    Sidebar --> UIPrimitives
    ContextPanel --> UIPrimitives
    SlashMenu --> UIPrimitives
    SettingsPanel --> UIPrimitives
    WebSearchUI --> UIPrimitives
    QueryClient --> Editor
    QueryClient --> Sidebar
    QueryClient --> ContextPanel
    QueryClient --> SlashMenu
    SettingsProv --> Editor
    ThemeProv --> Editor
    AIIndicator --> Editor

    %% Frontend to Backend
    ReactFrontend["React Frontend"]:::uiInvisible
    User --> ReactFrontend
    ReactFrontend -->|HTTP requests| APIIndex
    SharedSchema --- ReactFrontend

    %% API internal
    APIIndex --> Routes
    Routes --> Controllers
    SharedSchema --- Routes

    %% Controllers to Agent, DB, FileOps
    AIAgentCtrl --> AgentCore
    AIAgentCtrl --> Pipeline
    AIAgentCtrl --> OpenAICtrl
    AIAgentCtrl --> WebSearchCtrl
    SlashCtrl --> AIAgentCtrl
    WebSearchCtrl --> WebSearchExt
    OpenAICtrl --> OpenAI
    FileOps -->|read/write| FileOps
    DBConn --> Postgres
    DBStorage --> Postgres

    %% API interactions
    Controllers --> DBConn
    Controllers --> DBStorage
    Controllers --> FileOps

    %% AI Agent Engine to externals
    AgentCore --> OpenAI
    AgentCore --> Ollama
    AgentCore --> WebSearchExt

    %% Backend to Frontend response
    APIIndex -->|HTTP response| ReactFrontend

    %% Database and Migrations
    DBConfig --> Postgres
    DBMigrate --> Migrations
    Migrations --> Postgres

    %% Tests
    Tests --> AIAgentCtrl
    Tests --> Routes

    %% Click Events
    click Editor "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/client/src/components/Editor.tsx"
    click ContextPanel "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/client/src/components/ContextPanel.tsx"
    click SlashMenu "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/client/src/components/SlashCommandMenu.tsx"
    click SettingsPanel "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/client/src/components/SettingsPanel.tsx"
    click Sidebar "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/client/src/components/Sidebar.tsx"
    click AIIndicator "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/client/src/components/AIProcessingIndicator.tsx"
    click WebSearchUI "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/client/src/components/WebSearch.tsx"
    click UIPrimitives "https://github.com/0-cyberdyne-systems-0/wordplay/tree/main/client/src/components/ui"
    click QueryClient "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/client/src/lib/queryClient.ts"
    click SettingsProv "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/client/src/providers/SettingsProvider.tsx"
    click ThemeProv "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/client/src/providers/ThemeProvider.tsx"
    click APIIndex "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/server/index.ts"
    click Routes "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/server/routes.ts"
    click AIAgentCtrl "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/server/ai-agent.ts"
    click SlashCtrl "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/server/slash-commands.ts"
    click WebSearchCtrl "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/server/web-search.ts"
    click OpenAICtrl "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/server/openai.ts"
    click FileOps "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/server/file-operations.ts"
    click DBConfig "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/drizzle.config.ts"
    click DBConn "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/server/db.ts"
    click DBStorage "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/server/db-storage.ts"
    click DBMigrate "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/server/db-migrate.ts"
    click Migrations "https://github.com/0-cyberdyne-systems-0/wordplay/tree/main/migrations/"
    click SharedSchema "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/shared/schema.ts"
    click DocFlow "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/LLM_PIPELINE_FLOW.md"
    click Tests "https://github.com/0-cyberdyne-systems-0/wordplay/blob/main/test-*.js"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085
    classDef api fill:#d4edda,stroke:#155724
    classDef engine fill:#fff3cd,stroke:#856404
    classDef external fill:#f8d7da,stroke:#721c24
    classDef db fill:#d6d8db,stroke:#1b1e21
    classDef state fill:#e2e3e5,stroke:#818182
    classDef shared fill:#e2f0d9,stroke:#3c763d
    classDef doc fill:#f0f0f0,stroke:#333
    classDef test fill:#fde2e1,stroke:#c82333
    classDef uiInvisible fill:#ffffff,stroke:#ffffff,stroke-width:0

    class ReactFrontend ui
    class APIIndex,Routes,Controllers api
    class AgentCore,Pipeline engine
    class OpenAI,Ollama,WebSearchExt external
    class Postgres,DBConfig,DBMigrate,Migrations db
    class QueryClient,SettingsProv,ThemeProv state
    class SharedSchema shared
    class DocFlow doc
    class Tests test
```
