# antiwork/shortest architecture

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

- Interactive diagram: https://gitdiagram.com/antiwork/shortest
- Repository: https://github.com/antiwork/shortest

## Overview

##### Main components
- Frontend (Web Dashboard)
- Next.js App (app/ and components/)
- UI Components & Layouts
- Backend/API (Server-side)
- Next.js API Routes (app/api/*)
– generate-tests
– GitHub webhook
– Stripe checkout & webhook
– test/assert-bearer
- Shared server logic (lib/*)
– Database (lib/db via Drizzle ORM + migrations)
– Payments (lib/payments/stripe)
– GitHub integrations (lib/github, lib/github-stars)
– Utilities (lib/utils-server)
- Database
- Postgres (managed via Vercel Postgres)
- Drizzle ORM migrations + seed
- Authentication
- Clerk (GitHub-only login, 2FA)
- Third-Party Services
- Anthropic Claude AI API
- Stripe (Payments & Webhooks)
- Mailosaur (Email testing)
- GitHub OAuth & Webhooks
- CLI Package (“@antiwork/shortest” in packages/shortest)
- CLI entrypoint & command definitions (src/cli)
- Core layers (src/core):
– Framework detector
– App analyzer (Next.js AST + file tree)
– Builder & Compiler (bundling test code)
– Test planner & generator (system prompts → code)
– Runner (spawns Playwright, orchestrates test execution)
- AI layer (src/ai): Provider adapters + prompts + tools
- Browser integration (Playwright)
- Cache, logging, utils
- Developer Machine
- Local code editor & terminal
- “shortest init” → config + .env
- “pnpm shortest” → runs CLI tests

##### Relationships and data flows
- User → Browser → Next.js Frontend
- Frontend ↔ Clerk (Auth)
- Frontend/API → Database (Drizzle → Postgres)
- API webhook endpoints → Third-party services (Stripe, GitHub)
- Developer → CLI (shortest) →
- AI Provider (Anthropic)
- CLI Core → Playwright → Local browser → Next.js app (UI & API) → DB & externals
- Lifecycle hooks/callbacks in tests → direct DB queries via lib/db

##### Architectural patterns & design principles
- Monorepo with pnpm workspaces (next.config.ts, pnpm-workspace.yaml)
- Next.js 14 using Server Actions & Server Components
- Layered architecture in CLI: CLI → Core → AI → Browser → Runner
- API routes as micro-endpoints for distinct concerns
- Shared code (lib/) to avoid duplication between web and tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Web App Layer
    subgraph "Web App Layer"
        direction TB

        subgraph "UI Layer"
            direction TB
            NextApp["Next.js App (app/)"]:::internal
            UIComponents["UI Components & Layouts (components/ui/)"]:::internal
            HooksLog["use-log-groups.ts"]:::internal
            HooksToast["use-toast.ts"]:::internal
        end

        subgraph "Server/API Layer"
            direction TB
            API_Generate["API Route: /generate-tests"]:::internal
            API_GHWebhook["API Route: /github/webhook"]:::internal
            API_StripeCheckout["API Route: /stripe/checkout"]:::internal
            API_StripeWebhook["API Route: /stripe/webhook"]:::internal
            API_AssertBearer["API Route: /test/assert-bearer"]:::internal

            subgraph "Shared Libs"
                direction TB
                DB_Drizzle["Drizzle ORM (lib/db/drizzle.ts)"]:::internal
                DB_Migrate["Migrations (lib/db/migrate.ts & lib/db/migrations/)"]:::internal
                DB_Queries["DB Queries (lib/db/queries.ts)"]:::internal
                DB_Schema["DB Schema (lib/db/schema.ts)"]:::internal
                DB_Seed["DB Seed (lib/db/seed.ts)"]:::internal
                Payments["Payments Logic (lib/payments/stripe.ts)"]:::internal
                GitHubInt["GitHub Integrations (lib/github.ts & lib/github-stars.ts)"]:::internal
                UtilsServer["Utilities (lib/utils-server.ts)"]:::internal
                Config["Config & Env (lib/config/index.ts & schema.ts)"]:::internal
            end

            Postgres[(Postgres DB)]:::external
            Clerk["Clerk Auth"]:::external
            Stripe["Stripe"]:::external
            GitHub["GitHub"]:::external
            Mailosaur["Mailosaur"]:::external
        end
    end

    %% CLI Testing Layer
    subgraph "CLI Testing Layer"
        direction TB

        CLI_Interface["CLI Interface (packages/shortest/)"]:::cli

        subgraph "Core Modules"
            direction TB
            FD["Framework Detector"]:::cli
            Analyzer["App Analyzer"]:::cli
            Builder["Builder"]:::cli
            Compiler["Compiler"]:::cli
            Planner["Test Planner"]:::cli
            Generator["Test Generator"]:::cli
            Runner["Runner"]:::cli
        end

        subgraph "AI Layer"
            direction TB
            AIProvider["Provider & Prompts"]:::cli
            AITools["AI Tools"]:::cli
        end

        Browser["Playwright Browser"]:::cli
        CacheMod["Cache Module"]:::cli
        LogMod["Logging Module"]:::cli
        CLIUtils["CLI & Shared Utils"]:::cli
    end

    %% External Relationships
    User["User"]:::external
    Dev["Developer"]:::external
    BrowserClient["Browser"]:::external

    %% Flows
    User -->|"visits"| BrowserClient -->|"HTTP"| NextApp
    NextApp -->|"uses hooks"| HooksLog
    NextApp --> HooksToast
    NextApp -->|"fetches data"| API_Generate
    API_Generate -->|"reads/writes"| Postgres
    API_Generate -->|"calls"| DB_Drizzle
    API_Generate -->|"uses"| DB_Queries
    API_StripeCheckout -->|"Webhook"| Stripe
    API_StripeWebhook --> Stripe
    API_GHWebhook -->|"Webhook"| GitHub
    API_AssertBearer -->|"auth check"| Clerk

    API_Generate -->|"uses lib"| Payments
    API_Generate -->|"uses lib"| GitHubInt
    API_Generate -->|"uses lib"| UtilsServer
    API_Generate -->|"uses lib"| Config

    API_Generate --> Postgres
    API_StripeCheckout --> Postgres
    API_StripeWebhook --> Postgres

    API_Generate --> Mailosaur

    Dev -->|"runs"| CLI_Interface
    CLI_Interface --> FD
    CLI_Interface --> Analyzer
    Analyzer --> FD
    Analyzer --> Planner
    Planner --> Generator
    Generator --> Runner
    Runner --> Browser
    Browser --> NextApp
    Runner --> Postgres
    Runner --> Stripe
    Runner --> GitHub
    CLI_Interface --> AIProvider
    AIProvider --> AITools
    CLI_Interface --> CacheMod
    CLI_Interface --> LogMod
    CLI_Interface --> CLIUtils

    %% Click Events - Web App
    click NextApp "https://github.com/antiwork/shortest/tree/main/app/"
    click UIComponents "https://github.com/antiwork/shortest/tree/main/components/ui/"
    click HooksLog "https://github.com/antiwork/shortest/blob/main/hooks/use-log-groups.ts"
    click HooksToast "https://github.com/antiwork/shortest/blob/main/hooks/use-toast.ts"
    click API_Generate "https://github.com/antiwork/shortest/blob/main/app/api/generate-tests/route.ts"
    click API_Generate "https://github.com/antiwork/shortest/blob/main/app/api/generate-tests/schema.ts"
    click API_GHWebhook "https://github.com/antiwork/shortest/blob/main/app/api/github/webhook/route.ts"
    click API_StripeCheckout "https://github.com/antiwork/shortest/blob/main/app/api/stripe/checkout/route.ts"
    click API_StripeWebhook "https://github.com/antiwork/shortest/blob/main/app/api/stripe/webhook/route.ts"
    click API_AssertBearer "https://github.com/antiwork/shortest/blob/main/app/api/test/assert-bearer/route.ts"
    click DB_Drizzle "https://github.com/antiwork/shortest/blob/main/lib/db/drizzle.ts"
    click DB_Migrate "https://github.com/antiwork/shortest/blob/main/lib/db/migrate.ts"
    click DB_Migrate "https://github.com/antiwork/shortest/tree/main/lib/db/migrations/"
    click DB_Queries "https://github.com/antiwork/shortest/blob/main/lib/db/queries.ts"
    click DB_Schema "https://github.com/antiwork/shortest/blob/main/lib/db/schema.ts"
    click DB_Seed "https://github.com/antiwork/shortest/blob/main/lib/db/seed.ts"
    click Payments "https://github.com/antiwork/shortest/blob/main/lib/payments/stripe.ts"
    click Payments "https://github.com/antiwork/shortest/blob/main/lib/payments/actions.ts"
    click GitHubInt "https://github.com/antiwork/shortest/blob/main/lib/github.ts"
    click GitHubInt "https://github.com/antiwork/shortest/blob/main/lib/github-stars.ts"
    click UtilsServer "https://github.com/antiwork/shortest/blob/main/lib/utils-server.ts"
    click Config "https://github.com/antiwork/shortest/blob/main/lib/config/index.ts"
    click Config "https://github.com/antiwork/shortest/blob/main/lib/config/schema.ts"

    %% Click Events - CLI
    click CLI_Interface "https://github.com/antiwork/shortest/tree/main/packages/shortest/"
    click CLI_Interface "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/cli/bin.ts"
    click CLI_Interface "https://github.com/antiwork/shortest/tree/main/packages/shortest/src/cli/commands/"
    click FD "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/core/framework-detector/index.ts"
    click Analyzer "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/core/app-analyzer/next-js-analyzer.ts"
    click Analyzer "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/core/app-analyzer/utils/get-tree-structure.ts"
    click Builder "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/core/builder/index.ts"
    click Compiler "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/core/compiler/index.ts"
    click Planner "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/core/test-planner/index.ts"
    click Planner "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/core/test-planner/system-prompt.ts"
    click Generator "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/core/test-generator/index.ts"
    click Runner "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/core/runner/index.ts"
    click AIProvider "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/ai/provider.ts"
    click AIProvider "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/ai/prompts/index.ts"
    click AITools "https://github.com/antiwork/shortest/tree/main/packages/shortest/src/ai/tools/"
    click Browser "https://github.com/antiwork/shortest/tree/main/packages/shortest/src/browser/"
    click CacheMod "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/cache/index.ts"
    click LogMod "https://github.com/antiwork/shortest/blob/main/packages/shortest/src/log/index.ts"
    click CLIUtils "https://github.com/antiwork/shortest/tree/main/packages/shortest/src/utils/"
    click CLIUtils "https://github.com/antiwork/shortest/tree/main/packages/shortest/src/cli/utils/"
    click CLIUtils "https://github.com/antiwork/shortest/blob/main/lib/utils.ts"

    %% Styles
    classDef internal fill:#e0f7fa,stroke:#006064,color:#006064
    classDef external fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef cli fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a
```
