# samrolken/nokode architecture

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

- Interactive diagram: https://gitdiagram.com/samrolken/nokode
- Repository: https://github.com/samrolken/nokode

## Overview

##### Project type and purpose
- This is a single‐service, AI‐driven backend web server (“nokode”) that implements a CRUD contact manager entirely by deferring every request to a large language model (LLM). There is no traditional application logic—every HTTP request is handled by asking the LLM “what should I do?” and letting it orchestrate three tools (database, webResponse, updateMemory).

##### File structure
- Top‐level:
- package.json / package-lock.json – Node.js dependencies and scripts
- .env.example – LLM_PROVIDER, API key, model settings
- src/
– config/index.js – central configuration loader
– server.js – starts HTTP server
– middleware/llm-handler.js – core Express‐style middleware that captures incoming requests and invokes the LLM
– tools/
· database.js – runs SQL against SQLite
· webResponse.js – builds HTTP responses (HTML, JSON)
· memory.js – reads/writes feedback to disk
– utils/
· logger.js – logs requests, errors
· prompt-loader.js / memory-loader.js – load prompt templates and memory records
- No frontend code—HTML/JS is generated at runtime by the LLM via webResponse.

##### Key insights from README
- The LLM is the “app logic.” Three tools define the system boundary.
- The database schema and UI are invented by the model on the fly.
- Every request is ~30–60 s (LLM inference + tool I/O).
- Persistent memory is stored as Markdown for “updateMemory.”

##### Main components and their relationships
a. External client (Browser or API consumer)
b. HTTP Server (Node.js / Express‐like)
c. LLM Handler middleware
d. LLM Provider (Anthropic Claude API)
e. Tool Interfaces inside Node.js:
– Database tool → SQLite engine on disk
– webResponse tool → HTML/JSON builder
– updateMemory tool → feedback store (Markdown files)
f. Utilities (logger, prompt/memory loaders)
g. Configuration module (env, model, API keys)

##### Architectural pattern and design principles
- Monolithic, single‐process service
- Plugin pattern for tools: each tool exposes a simple API that the LLM can call
- Middleware pipeline: HTTP request → LLM handler → generateText → tool calls → response
- Separation of concerns: config, middleware, tools, utils all isolated

[ Client ] → [ HTTP Server ] → [ LLM Handler ] → [ LLM Provider ]
↓                    ↓
[ Tool Interfaces ] ←――――――
/     |      \
[Database] [webResponse] [updateMemory]
↓              ↑
[SQLite DB]     [Markdown files]
- Tool calls from the LLM to each tool interface
- Data flow from database back into the response

##### Detail level
- Every module group: config, middleware, tools, utils.
- Prompt-loader and memory-loader feeding into the LLM handler.
- Environment variables flowing into config.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["Browser / API Consumer"]:::external

    %% Node.js Service Components
    subgraph "Node.js Service"
        direction TB
        Env[".env.example"]:::config
        Pkg["package.json"]:::config
        Config["src/config/index.js"]:::config
        Logger["src/utils/logger.js"]:::utils
        PromptLoader["src/utils/prompt-loader.js"]:::utils
        MemoryLoader["src/utils/memory-loader.js"]:::utils
        Server["src/server.js<br/>HTTP Server (port 3001)"]:::component
        Middleware["src/middleware/llm-handler.js<br/>LLM Handler"]:::component

        subgraph "Tools"
            direction TB
            ToolsIndex["src/tools/index.js<br/>Tools Aggregator"]:::component
            DBTool["src/tools/database.js<br/>Database Tool"]:::component
            WebResp["src/tools/webResponse.js<br/>WebResponse Tool"]:::component
            MemTool["src/tools/memory.js<br/>UpdateMemory Tool"]:::component
        end
    end

    %% External LLM Provider
    LLM["Anthropic Claude API<br/>LLM Provider"]:::externalService

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        SQLite["SQLite DB"]:::database
        Markdown["Markdown Files"]:::database
    end

    %% Connections
    Client -->|"HTTP request"| Server
    Server -->|"passes to"| Middleware

    Env -->|"env variables"| Config
    Pkg -->|"defines deps & scripts"| Server
    Config -->|"config data"| Server

    Logger -->|"logs"| Middleware
    PromptLoader -->|"load prompts"| Middleware
    MemoryLoader -->|"load memory"| Middleware

    Middleware -->|"generateText() call"| LLM
    LLM -->|"response tokens"| Middleware

    Middleware -->|"invokes tools via Aggregator"| ToolsIndex
    ToolsIndex --> DBTool
    ToolsIndex --> WebResp
    ToolsIndex --> MemTool

    DBTool -->|"SQL I/O"| SQLite
    WebResp -->|"build response"| Middleware
    MemTool -->|"read/write feedback"| Markdown

    Middleware -->|"HTTP response"| Client

    %% Click Events
    click Config "https://github.com/samrolken/nokode/blob/main/src/config/index.js"
    click Server "https://github.com/samrolken/nokode/blob/main/src/server.js"
    click Middleware "https://github.com/samrolken/nokode/blob/main/src/middleware/llm-handler.js"
    click DBTool "https://github.com/samrolken/nokode/blob/main/src/tools/database.js"
    click WebResp "https://github.com/samrolken/nokode/blob/main/src/tools/webResponse.js"
    click MemTool "https://github.com/samrolken/nokode/blob/main/src/tools/memory.js"
    click ToolsIndex "https://github.com/samrolken/nokode/blob/main/src/tools/index.js"
    click Logger "https://github.com/samrolken/nokode/blob/main/src/utils/logger.js"
    click PromptLoader "https://github.com/samrolken/nokode/blob/main/src/utils/prompt-loader.js"
    click MemoryLoader "https://github.com/samrolken/nokode/blob/main/src/utils/memory-loader.js"
    click Env "https://github.com/samrolken/nokode/blob/main/.env.example"
    click Pkg "https://github.com/samrolken/nokode/blob/main/package.json"

    %% Styles
    classDef external fill:#ffd699,stroke:#333,stroke-width:1px
    classDef externalService fill:#b3e6b3,stroke:#333,stroke-width:1px
    classDef component fill:#99ccff,stroke:#333,stroke-width:1px
    classDef config fill:#c2f0c2,stroke:#333,stroke-width:1px
    classDef utils fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef database fill:#e6e6e6,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
