# shadrackb1/research-in-a-stick architecture

> Architecture diagram of the GitHub repository shadrackb1/research-in-a-stick, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shadrackb1/research-in-a-stick
- Repository: https://github.com/shadrackb1/research-in-a-stick

## Overview

Research-in-a-Stick is an offline-first research desk served locally in a browser. The user enters through the dashboard; HTTP routes dispatch chat and research requests to the assistant or dedicated tools, which return responses for display. Research spans local model conversation, seed-library lookup, uploaded-document retrieval, citations, CSV analysis, and offline wiki access; math, Python, and file tools are also available through skills. The README documents these capabilities, but several implementations were not sampled, so only documented subsystem presence is shown where wiring is uncertain.

Main entry points: [`ris/server.py`](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/server.py) (Local HTTP Server), [`ris/skills.py`](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/skills.py) (Skills Router), [`ris/static/app.js`](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/static/app.js) (Chat Dashboard), [`ris/ai.py`](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/ai.py) (Research Assistant)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_dashboard["Chat Dashboard<br/>[app.js]"]
end

subgraph group_runtime["Request Runtime"]
  node_http_server["Local HTTP Server<br/>[server.py]"]
  node_assistant["Research Assistant<br/>[ai.py]"]
  node_skill_router["Skills Router<br/>[skills.py]"]
end

subgraph group_knowledge["Research Sources"]
  node_library["Seed Knowledge<br/>[library.py]"]
  node_library_files["Knowledge Packs"]
  node_document_rag["Document Retrieval<br/>[rag.py]"]
  node_uploads["Uploaded Documents"]
  node_zim_packs["Wiki ZIM Packs"]
end

subgraph group_tools["Research Tools"]
  node_citations["Citation Formatter<br/>[citations.py]"]
  node_csv_analysis["CSV Analysis<br/>[analysis.py]"]
  node_sample_csv["Survey Sample<br/>[student_survey.csv]"]
  node_runtime_tools["Local Power Tools<br/>[tools_runtime.py]"]
end

subgraph group_local_services["Offline Services"]
  node_local_model["Local LLM<br/>[local_llm.py]"]
  node_kiwix["Kiwix Wiki<br/>[wiki.py]"]
  node_updater["Content Updater<br/>[updater.py]"]
end

node_student(("Student"))
node_content_feed["Online Content Feed"]

node_student -->|"asks or selects"| node_dashboard
node_dashboard -->|"sends requests"| node_http_server
node_http_server -->|"returns results"| node_dashboard
node_http_server -->|"dispatches chat"| node_assistant
node_assistant -->|"requests completion"| node_local_model
node_assistant -->|"runs skills"| node_skill_router
node_skill_router -->|"searches"| node_library
node_library -->|"reads packs"| node_library_files
node_skill_router -->|"searches documents"| node_document_rag
node_document_rag -->|"indexes and retrieves"| node_uploads
node_http_server -->|"searches library"| node_library
node_http_server -->|"retrieves and answers"| node_document_rag
node_http_server -->|"formats citations"| node_citations
node_skill_router -->|"formats citations"| node_citations
node_http_server -->|"analyzes CSV"| node_csv_analysis
node_csv_analysis -->|"reads sample"| node_sample_csv
node_skill_router -->|"analyzes data"| node_csv_analysis
node_skill_router -->|"runs local tools"| node_runtime_tools
node_http_server -->|"checks or starts wiki"| node_kiwix
node_skill_router -->|"checks or searches"| node_kiwix
node_kiwix -->|"serves packs"| node_zim_packs
node_http_server -.->|"checks update status"| node_updater
node_dashboard -.->|"requests content update"| node_http_server
node_updater -.->|"downloads packs"| node_content_feed

click node_dashboard "https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/static/app.js"
click node_http_server "https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/server.py"
click node_assistant "https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/ai.py"
click node_skill_router "https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/skills.py"
click node_library "https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/library.py"
click node_library_files "https://github.com/shadrackb1/research-in-a-stick/tree/main/data/library"
click node_document_rag "https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/rag.py"
click node_citations "https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/citations.py"
click node_csv_analysis "https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/analysis.py"
click node_sample_csv "https://github.com/shadrackb1/research-in-a-stick/blob/main/data/samples/student_survey.csv"
click node_runtime_tools "https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/tools_runtime.py"
click node_local_model "https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/local_llm.py"
click node_kiwix "https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/wiki.py"
click node_updater "https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/updater.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard toneBlue
class node_http_server,node_assistant,node_skill_router toneAmber
class node_library,node_library_files,node_document_rag,node_uploads,node_zim_packs toneMint
class node_citations,node_csv_analysis,node_sample_csv,node_runtime_tools toneRose
class node_local_model,node_kiwix,node_updater,node_student,node_content_feed toneIndigo
```

## Components

### User Interface

- [Chat Dashboard](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/static/app.js): `ris/static/app.js`

### Request Runtime

- [Local HTTP Server](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/server.py): `ris/server.py`
- [Research Assistant](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/ai.py): `ris/ai.py`
- [Skills Router](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/skills.py): `ris/skills.py`

### Research Sources

- [Seed Knowledge](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/library.py): `ris/library.py`
- [Knowledge Packs](https://github.com/shadrackb1/research-in-a-stick/tree/main/data/library): `data/library`
- [Document Retrieval](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/rag.py): `ris/rag.py`
- **Uploaded Documents**
- **Wiki ZIM Packs**

### Research Tools

- [Citation Formatter](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/citations.py): `ris/citations.py`
- [CSV Analysis](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/analysis.py): `ris/analysis.py`
- [Survey Sample](https://github.com/shadrackb1/research-in-a-stick/blob/main/data/samples/student_survey.csv): `data/samples/student_survey.csv`
- [Local Power Tools](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/tools_runtime.py): `ris/tools_runtime.py`

### Offline Services

- [Local LLM](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/local_llm.py): `ris/local_llm.py`
- [Kiwix Wiki](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/wiki.py): `ris/wiki.py`
- [Content Updater](https://github.com/shadrackb1/research-in-a-stick/blob/main/ris/updater.py): `ris/updater.py`

### Other components

- **Student**
- **Online Content Feed**

## Connections

- Student → Chat Dashboard: asks or selects
- Chat Dashboard → Local HTTP Server: sends requests
- Local HTTP Server → Chat Dashboard: returns results
- Local HTTP Server → Research Assistant: dispatches chat
- Research Assistant → Local LLM: requests completion
- Research Assistant → Skills Router: runs skills
- Skills Router → Seed Knowledge: searches
- Seed Knowledge → Knowledge Packs: reads packs
- Skills Router → Document Retrieval: searches documents
- Document Retrieval → Uploaded Documents: indexes and retrieves
- Local HTTP Server → Seed Knowledge: searches library
- Local HTTP Server → Document Retrieval: retrieves and answers
- Local HTTP Server → Citation Formatter: formats citations
- Skills Router → Citation Formatter: formats citations
- Local HTTP Server → CSV Analysis: analyzes CSV
- CSV Analysis → Survey Sample: reads sample
- Skills Router → CSV Analysis: analyzes data
- Skills Router → Local Power Tools: runs local tools
- Local HTTP Server → Kiwix Wiki: checks or starts wiki
- Skills Router → Kiwix Wiki: checks or searches
- Kiwix Wiki → Wiki ZIM Packs: serves packs
- Local HTTP Server → Content Updater: checks update status
- Chat Dashboard → Local HTTP Server: requests content update
- Content Updater → Online Content Feed: downloads packs