# ajndkr/lanarky architecture

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

- Interactive diagram: https://gitdiagram.com/ajndkr/lanarky
- Repository: https://github.com/ajndkr/lanarky

## Overview

##### Project type and purpose
- Lanarky is a **server-side web framework** built on FastAPI, tailored to help developers spin up LLM microservices with zero vendor lock-in.
- It provides a core application class, routing abstractions, streaming support (HTTP & WebSockets), adapter modules for LLM providers (OpenAI, LangChain), plus logging, events, and utility code.

##### File structure for architectural clues
- Top-level package `lanarky/` contains:
- `applications.py` – core `Lanarky` app class wrapping FastAPI
- `adapters/` – subpackages for each provider: `openai/`, `langchain/` with modules for dependencies, routing, callbacks, responses, utils
- `clients.py` – HTTP clients for invoking external LLM APIs
- `websockets.py` – WebSocket streaming support
- `events.py` & `logging.py` – event bus & logging hooks
- `responses.py`, `utils.py` – response normalization & utilities
- There are also `examples/` (demo microservices), `docs/`, `tests/`, configuration files (GitHub workflows, MkDocs, pyproject).

##### README for key insights
- Emphasizes **LLM-first**, **streaming**, **FastAPI** compatibility
- Shows the user flow: instantiate `Lanarky()`, include an adapter router (e.g. `OpenAIAPIRouter`), define POST endpoint returning a `Resource` object.

##### Main components
a. **Client (Browser / HTTP/WebSocket client)**
b. **Lanarky Application**
- FastAPI server underneath
- Core modules:
- Application core (`Lanarky`)
- Routing layer
- Dependency injection (from FastAPI + adapter-provided deps)
- Event bus & logging hooks
c. **Adapters**
- OpenAI adapter package
- LangChain adapter package
d. **Clients**
- HTTP / SDK clients to external LLM providers
e. **External LLM Services**
- OpenAI API
- LangChain-managed backends
f. **Streaming Components**
- HTTP streaming
- WebSockets (via `lanarky.websockets`)
g. **User’s Microservice Code**
- Custom router functions returning `Resource` objects
h. **Optional**
- Persistence / FAISS index (as shown in examples)
- Middleware or other integrations

##### Relationships and data flows
- Client → HTTP/WebSocket → FastAPI Server (Lanarky)
- FastAPI routes invoke **adapter router**
- Adapter router uses **dependencies** to build a `Resource` (system, user, stream flag)
- `Resource` handed off to **clients.py** which calls external LLM API
- Response streaming flows back through adapter → Lanarky → client
- **Event bus** captures events, **logging** hooks record metrics

##### Architectural patterns & design principles
- **Plugin / Adapter pattern** for provider-agnostic LLM calls
- **Dependency Injection** via FastAPI’s DI system
- **Streaming pipeline** abstracted over HTTP & WebSockets
- **Unopinionated core**: minimal footprint, zero vendor lock-in
- **Layer separation**: Core app vs. adapter vs. external system

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["Client (Browser/HTTP/WS)"]:::client

    %% User Microservice Code
    subgraph "User Microservice"
        Example1["ChatGPT Demo"]:::example
        Example2["PaulGPT Demo (with FAISS)"]:::example
    end

    %% Lanarky Core
    subgraph "Lanarky Core (FastAPI)" 
        CoreApp["Lanarky App\n(applications.py)"]:::core
        RouterLayer["Routing Layer"]:::core
        DI["Dependency Injection"]:::core
        EventBus["Event Bus\n(events.py)"]:::core
        Logging["Logging Hooks\n(logging.py)"]:::core
        Clients["LLM HTTP/SDK Clients\n(clients.py)"]:::core
        Responses["Response Normalization\n(responses.py)"]:::core
        Utils["Utilities\n(utils.py)"]:::core
        WebSockets["WebSocket Streaming\n(websockets.py)"]:::core
    end

    %% Adapters
    subgraph Adapters
        subgraph "OpenAI Adapter" 
            OA_Router["OpenAI Router\n(routing.py)"]:::adapter
            OA_Deps["OpenAI Dependencies\n(dependencies.py)"]:::adapter
            OA_Resp["OpenAI Responses\n(responses.py)"]:::adapter
            OA_Utils["OpenAI Utils\n(utils.py)"]:::adapter
        end
        subgraph "LangChain Adapter"
            LC_Router["LangChain Router\n(routing.py)"]:::adapter
            LC_Deps["LangChain Dependencies\n(dependencies.py)"]:::adapter
            LC_Callbacks["LangChain Callbacks\n(callbacks.py)"]:::adapter
            LC_Resp["LangChain Responses\n(responses.py)"]:::adapter
            LC_Utils["LangChain Utils\n(utils.py)"]:::adapter
        end
    end

    %% External Services
    subgraph "External LLM Services"
        OpenAI_API["OpenAI API"]:::external
        LangChain_Be["LangChain Backends"]:::external
    end

    %% Persistence
    subgraph "Persistence (Example)"
        FAISS1["index.faiss"]:::storage
        FAISS2["index.pkl"]:::storage
    end

    %% Flows
    Client -->|"HTTP/WS Request"| CoreApp
    CoreApp --> RouterLayer
    RouterLayer --> OA_Router
    RouterLayer --> LC_Router
    OA_Router -->|depends on| OA_Deps
    LC_Router -->|depends on| LC_Deps
    LC_Router --> LC_Callbacks
    OA_Router --> OA_Resp
    LC_Router --> LC_Resp
    OA_Router --> OA_Utils
    LC_Router --> LC_Utils
    RouterLayer --> DI
    DI -.->|injects| OA_Deps
    DI -.->|injects| LC_Deps

    OA_Router -->|calls| Clients
    LC_Router -->|calls| Clients
    Clients -->|"HTTP"| OpenAI_API
    Clients -->|"HTTP"| LangChain_Be

    OpenAI_API -->|stream| OA_Router
    LangChain_Be -->|stream| LC_Router

    OA_Router -->|resource→| Responses
    LC_Router -->|resource→| Responses
    Responses --> CoreApp
    CoreApp --> Client

    CoreApp --> EventBus
    CoreApp --> Logging
    CoreApp --> Utils
    CoreApp --> WebSockets

    %% Streaming flows
    Client -->|WebSocket| WebSockets
    WebSockets --> RouterLayer
    RouterLayer --> WebSockets
    WebSockets --> Client

    %% User code plugs in
    Example1 --> RouterLayer
    Example2 --> RouterLayer
    Example2 --> FAISS1
    Example2 --> FAISS2

    %% Click Events
    click CoreApp "https://github.com/ajndkr/lanarky/blob/main/lanarky/applications.py"
    click OA_Router "https://github.com/ajndkr/lanarky/blob/main/lanarky/adapters/openai/routing.py"
    click LC_Router "https://github.com/ajndkr/lanarky/blob/main/lanarky/adapters/langchain/routing.py"
    click OA_Deps "https://github.com/ajndkr/lanarky/blob/main/lanarky/adapters/openai/dependencies.py"
    click LC_Deps "https://github.com/ajndkr/lanarky/blob/main/lanarky/adapters/langchain/dependencies.py"
    click LC_Callbacks "https://github.com/ajndkr/lanarky/blob/main/lanarky/adapters/langchain/callbacks.py"
    click OA_Resp "https://github.com/ajndkr/lanarky/blob/main/lanarky/adapters/openai/responses.py"
    click LC_Resp "https://github.com/ajndkr/lanarky/blob/main/lanarky/adapters/langchain/responses.py"
    click Responses "https://github.com/ajndkr/lanarky/blob/main/lanarky/responses.py"
    click OA_Utils "https://github.com/ajndkr/lanarky/blob/main/lanarky/adapters/openai/utils.py"
    click LC_Utils "https://github.com/ajndkr/lanarky/blob/main/lanarky/adapters/langchain/utils.py"
    click Clients "https://github.com/ajndkr/lanarky/blob/main/lanarky/clients.py"
    click WebSockets "https://github.com/ajndkr/lanarky/blob/main/lanarky/websockets.py"
    click EventBus "https://github.com/ajndkr/lanarky/blob/main/lanarky/events.py"
    click Logging "https://github.com/ajndkr/lanarky/blob/main/lanarky/logging.py"
    click Utils "https://github.com/ajndkr/lanarky/blob/main/lanarky/utils.py"
    click Example1 "https://github.com/ajndkr/lanarky/blob/main/examples/chatgpt-clone/app.py"
    click Example2 "https://github.com/ajndkr/lanarky/blob/main/examples/paulGPT/app.py"
    click FAISS1 "https://github.com/ajndkr/lanarky/blob/main/examples/paulGPT/db/index.faiss"
    click FAISS2 "https://github.com/ajndkr/lanarky/blob/main/examples/paulGPT/db/index.pkl"

    %% Styles
    classDef client fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef core fill:#a8f0a5,stroke:#333,stroke-width:1px
    classDef adapter fill:#9fd4fa,stroke:#333,stroke-width:1px
    classDef external fill:#f7b267,stroke:#333,stroke-width:1px
    classDef example fill:#d6a8ff,stroke:#333,stroke-width:1px
    classDef storage fill:#ffe5a0,stroke:#333,stroke-width:1px
```
