# crafter-station/text0 architecture

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

- Interactive diagram: https://gitdiagram.com/crafter-station/text0
- Repository: https://github.com/crafter-station/text0

## Overview

##### Project type and purpose
- Text0 is a full-stack, serverless web application built on Next.js (App Router).
- It provides a “smart autocomplete” text editor that uses AI, vector databases, and external references.
- Key user flows:
- Sign in / authentication (Clerk)
- Document creation, editing, and auto-completion
- Reference management and integrations (GitHub, Notion, Linear, Discord)
- Voice input/output (UploadThing, browser media APIs)
- Background processing (Trigger.dev)

##### File structure and tech stack
- Top-level “app/” directory: Next.js pages, server and client components, API routes under “app/api/”
- “components/”, “app/(protected)/components/” and “components/ui/”: shared React UIs
- “lib/”: wrappers for auth, Redis, Vector DB, UploadThing, utility functions
- “hooks/”: custom React hooks for data fetching and UI state
- “trigger/” and root “actions/”: background jobs and automation scripts (Trigger.dev)
- Config files: next.config.ts, trigger.config.ts, biome.json, bun.lock, tsconfig.json
- README lists dependencies like Upstash Redis & Vector, AI SDK, Clerk, UploadThing, Tailwind, RadixUI, Vercel

##### Extract architectural insights from the README
- Serverless deployment on Vercel
- Authentication via Clerk
- Persistent state in Upstash Redis (sessions, cache) and Upstash Vector (embeddings)
- File uploads via UploadThing
- AI calls via AI SDK (OpenAI / Anthropic)
- Background workflows managed by Trigger.dev
- Integrations with external services via API routes

##### Main components & interactions
a. Client (Browser)
- React/Next.js (App Router)
- UI components: Editor, Data tables, Sidebars, Modals
- Media capture for voice input/output
- Auth flows (Clerk SDK)
b. Next.js Serverless Functions
- SSR/SSG pages (app/page.tsx, app/layout.tsx)
- API routes under app/api/ (chat, completion, docs, Github, Notion, Linear, Discord, transcribe, text-modification, uploadthing)
c. Background Processing
- Trigger.dev workers (trigger/process-document.ts)
- “actions/” and “trigger/” scripts invoking long-running tasks (e.g., reference syncing, vectorization)
d. Data Stores
- Upstash Redis (lib/redis.ts): session data, caching
- Upstash Vector (lib/vector.ts): embeddings for autocomplete and context search
- Local cookie store for small state (lib/local-cookies.ts)
e. External Services
- AI providers (OpenAI, Anthropic) via AI SDK
- GitHub, Notion, Linear, Discord integration APIs
- UploadThing for file storage
- Vercel for hosting & edge caching
f. Authentication & Authorization
- Clerk for user identity & session management
- Middleware.ts enforcing protected routes

##### Architectural patterns and principles
- Serverless micro-services: each API route is an independent function
- Separation of concerns:
- Presentation (React components, UI library)
- Business logic (server components, “lib/” helpers)
- Background jobs (Trigger.dev workflows)
- Data persistence (Redis, Vector)
- Event-driven workflows: file uploads or API calls trigger background vectorization and indexing
- Monorepo style but logically modular (app/, components/, lib/, hooks/, trigger/)

##### Detail
- Component names or file paths for major modules.
- Sequence of calls for a typical autocomplete request:
Browser → /api/completion → AI SDK → Upstash Vector → /api/completion → Browser
- Background indexing flow when a document is saved.
- Auth middleware gate between public and protected routes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Browser (Client)" 
        direction TB
        UIEditor["Text Editor UI"]:::client
        AICSSidebar["AI Chat Sidebar"]:::client
        AITrigger["AI Chat Trigger"]:::client
        ModelSelector["Model Selector"]:::client
        RefSelector["Reference Selector"]:::client
        TextToSpeech["Text-to-Speech"]:::client
        VoiceTranscription["Voice Transcription"]:::client
        ClerkSDK["Clerk SDK (Auth)"]:::client
        MediaCapture["Media Capture"]:::client
    end

    %% Next.js Serverless Layer
    subgraph "Next.js Serverless" 
        direction TB
        subgraph "SSR & SSG Pages"
            PageLayout["app/page.tsx & app/layout.tsx"]:::server
        end
        subgraph "API Routes"
            completionAPI["/api/completion"]:::server
            chatAPI["/api/chat"]:::server
            docsAPI["/api/docs/[doc_id]"]:::server
            referencesAPI["/api/references"]:::server
            subgraph "Integrations"
                GitHubData["/api/github/data"]:::server
                GitHubSync["/api/github/sync"]:::server
                NotionData["/api/notion/data"]:::server
                NotionSync["/api/notion/sync"]:::server
                LinearData["/api/linear/data"]:::server
                LinearSync["/api/linear/sync"]:::server
                DiscordData["/api/discord/data"]:::server
            end
            subgraph "Media & Text"
                TranscribeAPI["/api/transcribe"]:::server
                TextModAPI["/api/text-modification"]:::server
                UploadCore["/api/uploadthing/core"]:::server
                UploadAPI["/api/uploadthing"]:::server
            end
        end
        ClerkMiddleware["middleware.ts"]:::server
    end

    %% Background Processing
    subgraph "Background Workers (Trigger.dev)" 
        direction TB
        ProcessDoc["process-document.ts"]:::worker
        ActionAddRef["add-website-reference.ts"]:::worker
        ActionDocs["docs.ts"]:::worker
        ActionWebsites["websites.ts"]:::worker
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Redis["Upstash Redis"]:::datastore
        VectorDB["Upstash Vector"]:::datastore
        Cookies["Local Cookie Store"]:::datastore
    end

    %% Utilities & Hooks
    subgraph "Lib & Hooks"
        direction TB
        AuthLib["lib/auth/server.ts"]:::server
        RedisLib["lib/redis.ts"]:::datastore
        VectorLib["lib/vector.ts"]:::datastore
        CookiesLib["lib/local-cookies.ts"]:::datastore
        UploadLib["lib/uploadthing.ts"]:::external
        UtilsLib["lib/utils.ts"]:::external
        Hooks["hooks/*"]:::external
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AIProvider["AI SDK (OpenAI/Anthropic)"]:::external
        GitHub["GitHub API"]:::external
        Notion["Notion API"]:::external
        Linear["Linear API"]:::external
        Discord["Discord API"]:::external
        UploadThing["UploadThing Storage"]:::external
        Vercel["Vercel Hosting & Edge"]:::external
    end

    %% Connections
    UIEditor -->|fetch| completionAPI
    AICSSidebar -->|fetch| chatAPI
    AITrigger --> chatAPI
    ModelSelector --> chatAPI
    RefSelector --> referencesAPI
    TextToSpeech --> TranscribeAPI
    VoiceTranscription --> TranscribeAPI
    ClerkSDK --> ClerkMiddleware
    MediaCapture --> TranscribeAPI

    completionAPI -->|calls| AIProvider
    chatAPI -->|calls| AIProvider
    completionAPI -->|embeddings| VectorDB
    docsAPI --> Redis
    referencesAPI --> Redis
    GitHubData --> GitHub
    GitHubSync --> GitHub
    NotionData --> Notion
    NotionSync --> Notion
    LinearData --> Linear
    LinearSync --> Linear
    DiscordData --> Discord
    UploadAPI --> UploadThing
    UploadCore --> UploadThing

    UploadAPI --> ProcessDoc
    ProcessDoc --> VectorDB
    ActionAddRef --> Redis
    ActionDocs --> Redis
    ActionWebsites --> Redis

    PageLayout --> UIEditor

    AuthLib --> ClerkMiddleware
    RedisLib --> Redis
    VectorLib --> VectorDB
    CookiesLib --> Cookies
    UploadLib --> UploadThing
    Hooks --> docsAPI

    Vercel --> PageLayout
    Vercel --> completionAPI

    %% Click Events
    click UIEditor "https://github.com/crafter-station/text0/blob/main/app/(protected)/docs/[doc_id]/text-editor/index.tsx"
    click AICSSidebar "https://github.com/crafter-station/text0/blob/main/app/(protected)/docs/[doc_id]/text-editor/ai-chat-sidebar.tsx"
    click AITrigger "https://github.com/crafter-station/text0/blob/main/app/(protected)/docs/[doc_id]/text-editor/ai-chat-trigger.tsx"
    click ModelSelector "https://github.com/crafter-station/text0/blob/main/app/(protected)/docs/[doc_id]/text-editor/model-selector.tsx"
    click RefSelector "https://github.com/crafter-station/text0/blob/main/app/(protected)/docs/[doc_id]/text-editor/reference-selector.tsx"
    click TextToSpeech "https://github.com/crafter-station/text0/blob/main/app/(protected)/docs/[doc_id]/text-editor/text-to-speech.tsx"
    click VoiceTranscription "https://github.com/crafter-station/text0/blob/main/app/(protected)/docs/[doc_id]/text-editor/voice-transcription.tsx"
    click ClerkSDK "https://github.com/crafter-station/text0/blob/main/app/(auth)/sign-in/[[...sign-in]]/page.tsx"
    click AuthLib "https://github.com/crafter-station/text0/blob/main/lib/auth/server.ts"
    click ClerkMiddleware "https://github.com/crafter-station/text0/blob/main/middleware.ts"
    click completionAPI "https://github.com/crafter-station/text0/blob/main/app/api/completion/route.ts"
    click chatAPI "https://github.com/crafter-station/text0/blob/main/app/api/chat/route.ts"
    click docsAPI "https://github.com/crafter-station/text0/blob/main/app/api/docs/[doc_id]/route.ts"
    click GitHubData "https://github.com/crafter-station/text0/blob/main/app/api/github/data/route.ts"
    click GitHubSync "https://github.com/crafter-station/text0/blob/main/app/api/github/sync/route.ts"
    click NotionData "https://github.com/crafter-station/text0/blob/main/app/api/notion/data/route.ts"
    click NotionSync "https://github.com/crafter-station/text0/blob/main/app/api/notion/sync/route.ts"
    click LinearData "https://github.com/crafter-station/text0/blob/main/app/api/linear/data/route.ts"
    click LinearSync "https://github.com/crafter-station/text0/blob/main/app/api/linear/sync/route.ts"
    click DiscordData "https://github.com/crafter-station/text0/blob/main/app/api/discord/data/route.ts"
    click referencesAPI "https://github.com/crafter-station/text0/blob/main/app/api/references/route.ts"
    click TranscribeAPI "https://github.com/crafter-station/text0/blob/main/app/api/transcribe/route.ts"
    click TextModAPI "https://github.com/crafter-station/text0/blob/main/app/api/text-modification/route.ts"
    click UploadCore "https://github.com/crafter-station/text0/blob/main/app/api/uploadthing/core.ts"
    click UploadAPI "https://github.com/crafter-station/text0/blob/main/app/api/uploadthing/route.ts"
    click ProcessDoc "https://github.com/crafter-station/text0/blob/main/trigger/process-document.ts"
    click ActionAddRef "https://github.com/crafter-station/text0/blob/main/actions/add-website-reference.ts"
    click ActionDocs "https://github.com/crafter-station/text0/blob/main/actions/docs.ts"
    click ActionWebsites "https://github.com/crafter-station/text0/blob/main/actions/websites.ts"
    click RedisLib "https://github.com/crafter-station/text0/blob/main/lib/redis.ts"
    click VectorLib "https://github.com/crafter-station/text0/blob/main/lib/vector.ts"
    click CookiesLib "https://github.com/crafter-station/text0/blob/main/lib/local-cookies.ts"
    click UploadLib "https://github.com/crafter-station/text0/blob/main/lib/uploadthing.ts"
    click Hooks "https://github.com/crafter-station/text0/blob/main/hooks/use-document-references.ts"

    %% Styles
    classDef client fill:#D5E8D4,stroke:#82B366;
    classDef server fill:#FFF2CC,stroke:#D6B656;
    classDef worker fill:#F8CECC,stroke:#B85450;
    classDef datastore fill:#DAE8FC,stroke:#6C8EBF;
    classDef external fill:#E1D5E7,stroke:#9673A6;
```
