# srcbookdev/srcbook architecture

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

- Interactive diagram: https://gitdiagram.com/srcbookdev/srcbook
- Repository: https://github.com/srcbookdev/srcbook

## Overview

##### Main Components

a) Frontend Layer (packages/web):
- React-based web interface
- Components for app builder and notebook interfaces
- WebSocket client for real-time communication
- File system access integration

b) API Layer (packages/api):
- HTTP and WebSocket servers
- AI integration services
- TypeScript server management
- File system operations
- Database interactions

c) Shared Components (packages/shared):
- Type definitions
- Schemas
- Common utilities

d) Component Library (packages/components):
- Reusable UI components
- Cell components for notebooks
- Theme management

e) External Services:
- AI Providers (Anthropic Claude)
- Database (indicated by Drizzle migrations)
- Analytics service (PostHog)

**[User Browser]**
- ↕️
**[Frontend Layer]**
- App Builder UI
- Notebook UI
- WebSocket Client
- File System Access
- ↕️
**[API Layer]**
- HTTP Server
- WebSocket Server
- AI Services
- App Parser
- Plan Parser
- Code Generator
- TypeScript Server
- File System Manager
- Database Layer
- ↕️
**[External Services]**
- AI Provider (Claude)
- Analytics (PostHog)
- Database

##### Key Relationships to Highlight

- Bidirectional communication between frontend and API through both HTTP and WebSocket protocols
- File system interactions for local development
- AI service integration flow for code generation and app building
- Database interactions for storing user settings and app state
- TypeScript server integration for code analysis and completion

##### Important Architectural Patterns to Emphasize

- Monorepo structure using pnpm workspaces
- Microservices-like separation between different API functionalities
- Real-time communication through WebSocket channels
- Event-driven architecture for app updates and previews
- Plugin-based system for AI provider integration

##### Implementation Details

- Node.js runtime environment
- TypeScript as the primary language
- React for frontend components
- WebSocket for real-time updates
- Drizzle for database operations
- Docker support for containerization

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Browser
        UI[User Interface]
    end

    subgraph FrontendLayer[Frontend Layer]
        direction TB
        AppBuilder["App Builder UI"]
        NotebookUI["Notebook UI"]
        WSClient["WebSocket Client"]
        FSAccess["File System Access"]
        UIComponents["UI Components"]
        CellComponents["Cell Components"]
    end

    subgraph APILayer[API Layer]
        direction TB
        HTTPServer["HTTP Server"]
        WSServer["WebSocket Server"]
        FSManager["File System Manager"]
        
        subgraph AIServices[AI Services]
            direction TB
            AppParser["App Parser"]
            PlanParser["Plan Parser"]
            CodeGen["Code Generator"]
        end
        
        subgraph TSServer[TypeScript Server]
            direction TB
            TSImpl["Server Implementation"]
            MsgHandler["Message Handler"]
        end
        
        subgraph DBLayer[Database Layer]
            direction TB
            CoreDB["Core DB"]
            Migrations["Migrations"]
            Schema["Schema"]
        end
    end

    subgraph SharedLayer[Shared Components]
        direction TB
        Types["Types"]
        Schemas["Schemas"]
        Utils["Utilities"]
    end

    subgraph ExternalServices[External Services]
        direction TB
        Claude["AI Provider (Claude)"]
        PostHog["Analytics (PostHog)"]
        DB[(Database)]
    end

    %% Connections
    UI <--> FrontendLayer
    FrontendLayer <--> APILayer
    APILayer <--> ExternalServices
    SharedLayer --> FrontendLayer
    SharedLayer --> APILayer

    %% Click events
    click AppBuilder "https://github.com/srcbookdev/srcbook/tree/main/packages/web/src/components/apps"
    click NotebookUI "https://github.com/srcbookdev/srcbook/tree/main/packages/web/src/components/cells"
    click WSClient "https://github.com/srcbookdev/srcbook/tree/main/packages/web/src/clients/websocket"
    click FSAccess "https://github.com/srcbookdev/srcbook/blob/main/packages/web/src/lib/file-system-access.ts"
    click UIComponents "https://github.com/srcbookdev/srcbook/tree/main/packages/components/src/components/ui"
    click CellComponents "https://github.com/srcbookdev/srcbook/tree/main/packages/components/src/components/cells"
    click HTTPServer "https://github.com/srcbookdev/srcbook/blob/main/packages/api/server/http.mts"
    click WSServer "https://github.com/srcbookdev/srcbook/blob/main/packages/api/server/ws.mts"
    click FSManager "https://github.com/srcbookdev/srcbook/blob/main/packages/api/fs-utils.mts"
    click AppParser "https://github.com/srcbookdev/srcbook/blob/main/packages/api/ai/app-parser.mts"
    click PlanParser "https://github.com/srcbookdev/srcbook/blob/main/packages/api/ai/plan-parser.mts"
    click CodeGen "https://github.com/srcbookdev/srcbook/blob/main/packages/api/ai/generate.mts"
    click TSImpl "https://github.com/srcbookdev/srcbook/blob/main/packages/api/tsserver/tsserver.mts"
    click MsgHandler "https://github.com/srcbookdev/srcbook/blob/main/packages/api/tsserver/messages.mts"
    click CoreDB "https://github.com/srcbookdev/srcbook/tree/main/packages/api/db"
    click Migrations "https://github.com/srcbookdev/srcbook/tree/main/packages/api/drizzle"
    click Schema "https://github.com/srcbookdev/srcbook/blob/main/packages/api/db/schema.mts"
    click Types "https://github.com/srcbookdev/srcbook/tree/main/packages/shared/src/types"
    click Schemas "https://github.com/srcbookdev/srcbook/tree/main/packages/shared/src/schemas"
    click Utils "https://github.com/srcbookdev/srcbook/blob/main/packages/shared/src/utils.mts"

    %% Styling
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef api fill:#2ecc71,stroke:#27ae60,color:white
    classDef external fill:#f1c40f,stroke:#f39c12,color:black
    classDef database fill:#9b59b6,stroke:#8e44ad,color:white
    classDef ai fill:#e67e22,stroke:#d35400,color:white
    classDef shared fill:#1abc9c,stroke:#16a085,color:white

    class AppBuilder,NotebookUI,WSClient,FSAccess,UIComponents,CellComponents frontend
    class HTTPServer,WSServer,FSManager,TSImpl,MsgHandler api
    class Claude,PostHog,DB external
    class CoreDB,Migrations,Schema database
    class AppParser,PlanParser,CodeGen ai
    class Types,Schemas,Utils shared
```
