# i-am-alice/3rd-devs architecture

> Architecture diagram of the GitHub repository i-am-alice/3rd-devs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/i-am-alice/3rd-devs
- Repository: https://github.com/i-am-alice/3rd-devs

## Overview

##### Project type and purpose
- This is a monorepo of AI-Dev example microservices and frontends demonstrating various LLM-powered patterns (chat, retrieval, memory, embeddings, web search, database, audio/vision pipelines, etc.).
- Each example is a small Bun/Node HTTP server (app.ts) exposing one or two endpoints (/api/chat, /api/demo, etc.) that orchestrate prompt templates, service classes, and external APIs.

##### File structure
- Top-level directories:
- agent, assistant, better_rag, chain, chat, … – each contains an app.ts + Service classes + prompt/ types/ utils.
- audio-frontend, audio-map-frontend, voice-frontend – static frontends using HTML/TypeScript/Canvas/Audio APIs.
- db-related examples: database, qdrant, neo4j, algolia, sync, hybrid – each illustrating storage integrations.
- Shared patterns:
- app.ts (entrypoint) → HTTP endpoints → Service classes → Prompt templates → OpenAIService (or other API clients) → optional DataStore or external API → response.
- Config/build: bun.lockb, package.json, .env-example, tsconfig.json, vite.config.* for frontends.

##### README for additional insights
- The repo is organized by “lessons” (S01E01…S03E05) grouping examples.
- Common tech: Bun runtime, Node.js, TypeScript, OpenAI API, various external services (Firecrawl, Langfuse, Algolia, Qdrant, Neo4j), filesystem for context/memory.
- Each example demonstrates a specific pattern: thread summarization, search-augmented generation, memory, audio capture, vision, file context, etc.

a. Main components
- Clients
- CLI (curl, bun run <example>)
- Browser frontends (audio-frontend, audio-map-frontend, voice-frontend)
- API Gateway / HTTP Server
- app.ts per example (Bun)
- routing layer (/api/chat, /api/demo, other endpoints)
- Service Layer
- Controller delegates to Service classes (AssistantService, TextService, VectorService, DatabaseService, MemoryService, WebSearch, etc.)
- Prompt Layer
- Directory of prompt templates (prompts/…) grouped by domain (assistant, documents, web, think)
- Core LLM Client
- OpenAIService.ts
- External Integrations
- Firecrawl (websearch), Langfuse (logging), ElevenLabs (TTS), Google AI Studio (video API), Mistral (Pixtral), Linear webhook, Redis/RateLimiter, etc.
- Data Stores
- File system (files/context, memories)
- Vector DB (Qdrant)
- Search index (Algolia)
- Graph DB (Neo4j)
- SQL/NoSQL (DatabaseService)

b. Relationships and data flow
1. User/client sends HTTP request →
2. API server (app.ts) routes request →
3. Controller calls one or more Service classes →
4. Services assemble prompts from Prompt Layer →
5. OpenAIService (or other model client) invoked →
6. Optionally interact with Data Stores / external APIs →
7. Gather/aggregate results →
8. Return HTTP response to client

c. Architectural patterns
- Layered architecture: presentation (HTTP), application (services), domain (prompts & business logic), infrastructure (LLM client & external APIs), persistence (datastores)
- Single responsibility per example: each folder is a self-contained microservice
- Plugin-style prompt templates: interchangeable by domain
- Dependency injection via constructor parameters for Service classes

d. Key technologies
- Runtime: Bun + Node.js
- Language: TypeScript / JavaScript
- HTTP: Bun HTTP server
- LLM API: OpenAI
- Vector store: Qdrant
- Search: Algolia, Firecrawl
- Graph DB: Neo4j
- Logging/observability: Langfuse
- File I/O: native fs for context/memory
- Frontend: HTML/TypeScript/Vite for audio & voice demos

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients" 
        direction TB
        CLI["CLI (curl, bun run)"]:::client
        AudioFE["Audio Frontend"]:::client
        AudioMapFE["Audio-Map Frontend"]:::client
        VoiceFE["Voice Frontend"]:::client
    end

    %% API Server Layer
    subgraph "API Server / HTTP Gateway" 
        direction TB
        AgentApp["Agent app.ts"]:::server
        BetterRagApp["Better RAG app.ts"]:::server
        DatabaseApp["Database app.ts"]:::server
        MemoryApp["Memory app.ts"]:::server
        QdrantApp["Qdrant app.ts"]:::server
        Neo4jApp["Neo4j app.ts"]:::server
    end

    %% Service Layer
    subgraph "Service Layer" 
        direction TB
        AgentSvc["AgentService"]:::service
        TextSvc["TextService"]:::service
        VectorSvc["VectorService"]:::service
        DatabaseSvc["DatabaseService"]:::service
        MemorySvc["MemoryService"]:::service
        WebSearchSvc["WebSearch"]:::service
        LinearSvc["LinearService"]:::service
        ElevenLabsSvc["ElevenLabsService"]:::service
        LangfuseSvc["LangfuseService"]:::service
    end

    %% Prompt Layer
    subgraph "Prompt Layer" 
        direction TB
        AgentPrompts["agent/prompts/"]:::prompt
        AssistantPrompts["assistant/prompts/"]:::prompt
        WebPrompts["web/prompts/"]:::prompt
        TodoPrompts["todo/prompts/"]:::prompt
        NarrationPrompts["narration/prompts.ts"]:::prompt
    end

    %% LLM Client
    OpenAI["OpenAIService"]:::external

    %% External Integrations
    subgraph "External APIs" 
        direction TB
        Firecrawl["Firecrawl (WebSearch)"]:::external
        LangfuseExt["Langfuse Logging"]:::external
        ElevenLabsExt["ElevenLabs TTS"]:::external
        LinearExt["Linear Webhook"]:::external
    end

    %% Data Stores
    subgraph "Data Stores" 
        direction TB
        FileSystem["Filesystem (memories/)"]:::datastore
        QdrantDB["Qdrant (VectorStore)"]:::datastore
        AlgoliaDB["Algolia (Search Index)"]:::datastore
        Neo4jDB["Neo4j Graph DB"]:::datastore
        SQLDB["SQL/NoSQL DB"]:::datastore
        HybridSync["Hybrid Sync"]:::datastore
    end

    %% Main Flow
    CLI -->|requests| AgentApp
    AudioFE -->|HTTP/WebSocket| BetterRagApp
    AudioMapFE -->|HTTP/WebSocket| MemoryApp
    VoiceFE -->|HTTP/WebSocket| AudioMapFE
    AgentApp -->|calls| AgentSvc
    BetterRagApp -->|calls| TextSvc
    BetterRagApp -->|calls| VectorSvc
    DatabaseApp -->|calls| DatabaseSvc
    MemoryApp -->|calls| MemorySvc
    QdrantApp -->|calls| VectorSvc
    Neo4jApp -->|calls| DatabaseSvc

    AgentSvc -->|uses| AgentPrompts
    TextSvc -->|uses| TodoPrompts
    VectorSvc -->|uses| WebPrompts
    MemorySvc -->|uses| AssistantPrompts
    ElevenLabsSvc -->|uses| NarrationPrompts

    AgentSvc -->|invokes| OpenAI
    TextSvc -->|invokes| OpenAI
    VectorSvc -->|invokes| OpenAI
    DatabaseSvc -->|invokes| OpenAI
    MemorySvc -->|invokes| OpenAI

    WebSearchSvc -->|invokes| Firecrawl
    LangfuseSvc -->|invokes| LangfuseExt
    ElevenLabsSvc -->|invokes| ElevenLabsExt
    LinearSvc -->|invokes| LinearExt

    MemorySvc -->|reads/writes| FileSystem
    VectorSvc -->|queries| QdrantDB
    WebSearchSvc -->|indexes| AlgoliaDB
    DatabaseSvc -->|reads/writes| SQLDB
    DatabaseSvc -->|writes| Neo4jDB
    HybridSync -->|syncs| AlgoliaDB

    OpenAI -->|returns| AgentSvc
    OpenAI -->|returns| TextSvc
    OpenAI -->|returns| VectorSvc
    OpenAI -->|returns| DatabaseSvc
    OpenAI -->|returns| MemorySvc

    AgentSvc -->|response| CLI
    BetterRagApp -->|response| AudioFE
    MemoryApp -->|response| AudioMapFE
    Neo4jApp -->|response| CLI

    %% Click Events - Clients
    click AudioFE "https://github.com/i-am-alice/3rd-devs/blob/main/audio-frontend/index.html"
    click AudioMapFE "https://github.com/i-am-alice/3rd-devs/blob/main/audio-map-frontend/index.html"
    click VoiceFE "https://github.com/i-am-alice/3rd-devs/blob/main/voice-frontend/index.html"

    %% Click Events - API Server
    click AgentApp "https://github.com/i-am-alice/3rd-devs/blob/main/agent/app.ts"
    click BetterRagApp "https://github.com/i-am-alice/3rd-devs/blob/main/better_rag/app.ts"
    click DatabaseApp "https://github.com/i-am-alice/3rd-devs/blob/main/database/app.ts"
    click MemoryApp "https://github.com/i-am-alice/3rd-devs/blob/main/memory/app.ts"
    click QdrantApp "https://github.com/i-am-alice/3rd-devs/blob/main/qdrant/app.ts"
    click Neo4jApp "https://github.com/i-am-alice/3rd-devs/blob/main/neo4j/app.ts"

    %% Click Events - Services
    click AgentSvc "https://github.com/i-am-alice/3rd-devs/blob/main/agent/AgentService.ts"
    click TextSvc "https://github.com/i-am-alice/3rd-devs/blob/main/better_rag/TextService.ts"
    click VectorSvc "https://github.com/i-am-alice/3rd-devs/blob/main/better_rag/VectorService.ts"
    click DatabaseSvc "https://github.com/i-am-alice/3rd-devs/blob/main/database/DatabaseService.ts"
    click MemorySvc "https://github.com/i-am-alice/3rd-devs/blob/main/memory/MemoryService.ts"
    click WebSearchSvc "https://github.com/i-am-alice/3rd-devs/blob/main/websearch/WebSearch.ts"
    click LinearSvc "https://github.com/i-am-alice/3rd-devs/blob/main/linear/LinearService.ts"
    click ElevenLabsSvc "https://github.com/i-am-alice/3rd-devs/blob/main/narration/ElevenLabsService.ts"
    click LangfuseSvc "https://github.com/i-am-alice/3rd-devs/blob/main/langfuse/LangfuseService.ts"

    %% Click Events - Prompt Layer
    click AgentPrompts "https://github.com/i-am-alice/3rd-devs/tree/main/agent/prompts/"
    click AssistantPrompts "https://github.com/i-am-alice/3rd-devs/tree/main/assistant/prompts/"
    click WebPrompts "https://github.com/i-am-alice/3rd-devs/tree/main/web/prompts/"
    click TodoPrompts "https://github.com/i-am-alice/3rd-devs/tree/main/todo/prompts/"
    click NarrationPrompts "https://github.com/i-am-alice/3rd-devs/blob/main/narration/prompts.ts"

    %% Click Events - LLM Clients
    click OpenAI "https://github.com/i-am-alice/3rd-devs/blob/main/agent/OpenAIService.ts"
    click OpenAI "https://github.com/i-am-alice/3rd-devs/blob/main/better_rag/OpenAIService.ts"
    click OpenAI "https://github.com/i-am-alice/3rd-devs/blob/main/database/OpenAIService.ts"
    click OpenAI "https://github.com/i-am-alice/3rd-devs/blob/main/memory/OpenAIService.ts"
    click OpenAI "https://github.com/i-am-alice/3rd-devs/blob/main/qdrant/OpenAIService.ts"
    click OpenAI "https://github.com/i-am-alice/3rd-devs/blob/main/neo4j/OpenAIService.ts"
    click OpenAI "https://github.com/i-am-alice/3rd-devs/blob/main/websearch/OpenAIService.ts"

    %% Click Events - External Integrations
    click Firecrawl "https://github.com/i-am-alice/3rd-devs/blob/main/websearch/WebSearch.ts"
    click LangfuseExt "https://github.com/i-am-alice/3rd-devs/blob/main/langfuse/LangfuseService.ts"
    click ElevenLabsExt "https://github.com/i-am-alice/3rd-devs/blob/main/narration/ElevenLabsService.ts"
    click LinearExt "https://github.com/i-am-alice/3rd-devs/blob/main/linear/LinearService.ts"

    %% Click Events - Data Stores
    click FileSystem "https://github.com/i-am-alice/3rd-devs/tree/main/memory/memories/"
    click QdrantDB "https://github.com/i-am-alice/3rd-devs/blob/main/qdrant/VectorService.ts"
    click AlgoliaDB "https://github.com/i-am-alice/3rd-devs/blob/main/algolia/AlgoliaService.ts"
    click Neo4jDB "https://github.com/i-am-alice/3rd-devs/blob/main/neo4j/Neo4jService.ts"
    click Neo4jDB "https://github.com/i-am-alice/3rd-devs/blob/main/neo4j/init.ts"
    click SQLDB "https://github.com/i-am-alice/3rd-devs/blob/main/database/DatabaseService.ts"
    click HybridSync "https://github.com/i-am-alice/3rd-devs/blob/main/sync/DatabaseService.ts"
    click HybridSync "https://github.com/i-am-alice/3rd-devs/blob/main/sync/AlgoliaService.ts"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px;
    classDef server fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px;
    classDef service fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
    classDef prompt fill:#ffeeba,stroke:#856404,color:#856404,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-width:1px;
    classDef datastore fill:#e2e3e5,stroke:#818182,color:#818182,stroke-width:1px,stroke-dasharray: 2 2;
```
