# apteryxxyz/evaluate architecture

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

- Interactive diagram: https://gitdiagram.com/apteryxxyz/evaluate
- Repository: https://github.com/apteryxxyz/evaluate

## Overview

##### Project type and purpose
- This is a multi-app, monorepo (pnpm workspace + Turborepo) called “Evaluate,” comprising three client-side applications plus shared libraries.
- Purpose: let users run code in any language from anywhere—via a web IDE (Next.js website), a browser extension (Vite-powered), and a Discord bot (Node + discord.js).

##### File structure
- Top-level “apps/” directory holds three separate apps:
- browser-extension (Vite + TypeScript + React content & background scripts)
- discord-bot (slash commands, event handlers, Node service)
- website (Next.js v14 app directory, React components, serverless API routes)
- “packages/” directory holds reusable modules:
- engine (code-execution logic & remote fetch/compression)
- components, styles (shared React UI)
- Configs: shared tsconfig.*, .env templates, workflows for CI/CD, Husky hooks, Vercel ignore.

##### README
- Confirms three main products: website, browser extension, Discord bot
- No dedicated “backend” service in repo; execution happens via engine library calling Evaluate’s public API/gateways.
- Analytics with PostHog integrated in clients.

- Website (Next.js)
- Browser Extension (React + background/content scripts)
- Discord Bot (Node service)
- External Services:
- Evaluate Code-Execution API / Runtime cluster
- Discord API
- PostHog Analytics
- Website ←→ engine → Evaluate API → language runtimes → engine → Website
- Browser Extension scripts ←→ engine → Evaluate API → … → Extension
- Discord Bot ←→ engine → Evaluate API → … → Discord Bot → Discord Users
- All three clients send analytic events to PostHog
- Discord Bot interacts with Discord API (slash commands, events)
c. Architectural patterns & principles:
- Monorepo with workspace packages for maximum code reuse
- Clear separation of concerns: UI apps vs core engine vs utilities
- Serverless API routes (Next.js) vs long-running Node process (Discord bot)
- Content scripts + background scripts for extension isolation
d. Key technologies & frameworks:
- Next.js App Router, React, TypeScript
- Vite for extension bundling
- discord.js (or Discord REST/WS) for bot
- Importing shared “engine” module in each client
- pnpm + Turborepo for workspace orchestration
- PostHog for telemetry

##### Detail
- Break each client into subcomponents if needed (e.g., Next.js SSR vs API routes; extension’s background vs content scripts; bot’s command handlers vs event listeners)
- Environment/config flows (e.g., .env loading, CI pipelines) if they impact deployment

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Applications"
        subgraph "Website (Next.js)"
            WebsiteUI["Web UI"]:::client
            APIRoutes["Serverless API Routes"]:::client
            PHWeb["PostHog Service"]:::client
        end
        subgraph "Browser Extension"
            Content["Content Scripts"]:::client
            Background["Background Script"]:::client
            PHExt["PostHog Service"]:::client
        end
        subgraph "Discord Bot"
            Commands["Slash Commands"]:::client
            Handlers["Command Handlers"]:::client
            Events["Event Listeners"]:::client
            PHBot["PostHog Service"]:::client
        end
    end

    subgraph "Shared Libraries"
        Engine["Code-Execution Engine"]:::shared
        Components["Shared UI Components"]:::shared
        Styles["Shared Styles"]:::shared
        Helpers["Utility Helpers"]:::shared
        Hooks["Shared Hooks"]:::shared
        Shapes["Data Shapes & Types"]:::shared
        Scripts["CLI & Scripts"]:::shared
        TSConfig["TS Configs"]:::shared
    end

    subgraph "External Services"
        EvalAPI["Evaluate Code-Execution API/Runtime"]:::external
        DiscordAPI["Discord API"]:::external
        PostHog["PostHog Analytics"]:::external
    end

    %% Client to Engine
    WebsiteUI -->|"uses engine"| Engine
    APIRoutes -->|"uses engine"| Engine
    Content -->|"uses engine"| Engine
    Background -->|"uses engine"| Engine
    Commands -->|"uses engine"| Engine
    Handlers -->|"uses engine"| Engine
    Events -->|"uses engine"| Engine

    %% Engine to Execution Backend
    Engine -->|"request execution"| EvalAPI
    EvalAPI -->|"return results"| Engine

    %% Engine back to clients
    Engine --> WebsiteUI
    Engine --> Content
    Engine --> Background
    Engine --> Commands
    Engine --> Handlers
    Engine --> Events

    %% Analytics flows
    WebsiteUI --> PHWeb
    PHWeb --> PostHog
    Content --> PHExt
    PHExt --> PostHog
    Background --> PHExt
    Commands --> PHBot
    Handlers --> PHBot
    Events --> PHBot
    PHBot --> PostHog

    %% Discord interactions
    Commands -->|"slash commands"| DiscordAPI
    Events -->|"event stream"| DiscordAPI
    DiscordAPI -->|"events"| Events

    %% Click Events
    click WebsiteUI "https://github.com/apteryxxyz/evaluate/tree/main/apps/website"
    click APIRoutes "https://github.com/apteryxxyz/evaluate/tree/main/apps/website/src/app/api"
    click PHWeb "https://github.com/apteryxxyz/evaluate/blob/main/apps/website/src/services/posthog.ts"
    click Content "https://github.com/apteryxxyz/evaluate/tree/main/apps/browser-extension/src/content-script"
    click Background "https://github.com/apteryxxyz/evaluate/blob/main/apps/browser-extension/src/background/index.ts"
    click PHExt "https://github.com/apteryxxyz/evaluate/blob/main/apps/browser-extension/src/services/posthog.ts"
    click Commands "https://github.com/apteryxxyz/evaluate/tree/main/apps/discord-bot/src/commands"
    click Handlers "https://github.com/apteryxxyz/evaluate/tree/main/apps/discord-bot/src/handlers"
    click Events "https://github.com/apteryxxyz/evaluate/tree/main/apps/discord-bot/src/events"
    click PHBot "https://github.com/apteryxxyz/evaluate/blob/main/apps/discord-bot/src/services/posthog.ts"
    click Engine "https://github.com/apteryxxyz/evaluate/tree/main/packages/engine"
    click Components "https://github.com/apteryxxyz/evaluate/tree/main/packages/components"
    click Styles "https://github.com/apteryxxyz/evaluate/tree/main/packages/styles"
    click Helpers "https://github.com/apteryxxyz/evaluate/tree/main/packages/helpers"
    click Hooks "https://github.com/apteryxxyz/evaluate/tree/main/packages/hooks"
    click Shapes "https://github.com/apteryxxyz/evaluate/tree/main/packages/shapes"
    click Scripts "https://github.com/apteryxxyz/evaluate/tree/main/packages/scripts"
    click TSConfig "https://github.com/apteryxxyz/evaluate/blob/main/tsconfig.base.json"

    classDef client fill:#ADD8E6,stroke:#000
    classDef shared fill:#90EE90,stroke:#000
    classDef external fill:#FFA500,stroke:#000
```
