# ur-whitelab/llms-in-science architecture

> Architecture diagram of the GitHub repository ur-whitelab/llms-in-science, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ur-whitelab/llms-in-science
- Repository: https://github.com/ur-whitelab/llms-in-science

## Overview

##### Project Type and Purpose
- This repository is a modular, content-oriented “documentation monorepo” for a review paper on large language models (LLMs) and autonomous agents in chemistry.
- It aggregates five submodules (Agents, LLM, Sci_LLM, Sci_agents, LLMTimeline) plus an assets folder and core README/CONTRIBUTING instructions.
- Contributors add, update, and categorize literature under these topical modules; readers browse structured markdown pages.

##### File Structure Analysis
- Top-level:
- .gitmodules – defines four Git submodules (Agents, LLM, Sci_LLM, Sci_agents)
- README.md – overview and TOC linking into submodule READMEs
- CONTRIBUTING.md – guidelines for community contributions
- LLMTimeline – likely holds a generated timeline image or code to produce it
- Each submodule has its own README.md, subdividing content by topic (e.g., memory, planning, tools in Agents).
- No application code or build scripts: it’s purely markdown content managed via Git.

a. Main Components
- Monorepo Root (Git repository)
- Submodule Modules (Agents, LLM, Sci_LLM, Sci_agents)
- Shared Assets folder
- CONTRIBUTING and Governance docs
- External Services: GitHub hosting, GitHub Pages (optional for site rendering), arXiv badge service
- Contributors (Users/Authors)
- Readers/Viewers
b. Relationships and Interactions
– Contributors clone/fork monorepo → update module READMEs → commit to submodule or main repo → open Pull Request → GitHub CI (linting/spell-check) → merge → GitHub Pages deployment.
– Readers access rendered site via GitHub Pages → navigate root TOC → dive into submodule content → click assets (images, timeline).
– Submodules link back to root CONTRIBUTING.md for contribution guidelines.
– External badge services (shields.io, arXiv) dynamically fetch status to embed in README.
c. Architectural Patterns & Principles
– Modularity: each topic lives in its own submodule, enabling isolated updates.
– Single Source of Truth: root TOC unifies navigation.
– Git Submodule Pattern: keeps large content sections decoupled.
– Static-site friendly: markdown + GitHub Pages (no server runtime).
d. Key Technologies/Frameworks
- Git / Git Submodules
- Markdown for content
- GitHub (hosting, Pages, Issues, PRs)
- Shields.io & arXiv badge service
- (Optional) Static site generator: GitHub Pages Jekyll or MkDocs if configured

##### Detailed Elements to Capture
- Submodule links defined in .gitmodules
- Root TOC links to each module README
- CONTRIBUTING.md as the policy gate
- LLMTimeline image generation or storage
- assets directory as shared media resource
- External badge services and arXiv integration

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    Contributors["Contributors"]:::actor
    Readers["Readers"]:::actor

    %% GitHub Services
    subgraph "GitHub Platform"
        GitHubHost["GitHub Hosting"]:::cloud
        GitHubPages["GitHub Pages"]:::cloud
    end

    %% Continuous Integration
    CI["GitHub CI (lint/spell)"]:::external
    PR["Pull Request"]:::external
    Merge["Merge"]:::external

    %% Repo Components
    subgraph "Repository Governance"
        Gitmodules[".gitmodules"]:::governance
        ReadmeRoot["README.md"]:::governance
        ContribGuidelines["CONTRIBUTING.md"]:::governance
    end

    subgraph "Content Modules"
        AgentsModule["Agents (README.md)"]:::content
        LLMModule["LLM (README.md)"]:::content
        SciLLModule["Sci_LLM (README.md)"]:::content
        SciAgentsModule["Sci_agents (README.md)"]:::content
    end

    subgraph "Shared Resources"
        AssetDir["assets"]:::resources
        Timeline["LLMTimeline"]:::resources
    end

    %% External Badge Services
    subgraph "External Services"
        BadgeService["shields.io Badge API"]:::service
        ArxivService["arXiv Badge Service"]:::service
    end

    %% Relations: Contributors workflow
    Contributors -->|"clone/fork"| GitHubHost
    GitHubHost -->|"serve repo"| Gitmodules
    GitHubHost -->|"serve repo"| ReadmeRoot
    Contributors -->|"commit & push"| ReadmeRoot
    Contributors -->|"commit & push"| ContribGuidelines
    Contributors -->|"commit & push"| AgentsModule
    Contributors -->|"commit & push"| LLMModule
    Contributors -->|"commit & push"| SciLLModule
    Contributors -->|"commit & push"| SciAgentsModule
    Contributors -->|"commit & push"| AssetDir
    Contributors -->|"commit & push"| Timeline

    ReadmeRoot -->|"defines submodules"| Gitmodules
    ReadmeRoot -->|"links to modules"| AgentsModule
    ReadmeRoot -->|"links to modules"| LLMModule
    ReadmeRoot -->|"links to modules"| SciLLModule
    ReadmeRoot -->|"links to modules"| SciAgentsModule
    ReadmeRoot -->|"refers to guidelines"| ContribGuidelines

    AgentsModule <--> AssetDir
    LLMModule <--> AssetDir
    SciLLModule <--> AssetDir
    SciAgentsModule <--> AssetDir
    ReadmeRoot --> Timeline
    AgentsModule --> Timeline

    %% PR and CI
    Contributors -->|open PR| PR
    PR -->|trigger| CI
    CI -->|report status| GitHubHost
    PR -->|merged| Merge
    Merge -->|deploy| GitHubPages

    %% Readers workflow
    Readers -->|"browse site"| GitHubPages
    GitHubPages -->|"serve markdown"| ReadmeRoot
    ReadmeRoot -->|"navigate"| AgentsModule
    ReadmeRoot -->|"navigate"| LLMModule
    ReadmeRoot -->|"navigate"| SciLLModule
    ReadmeRoot -->|"navigate"| SciAgentsModule
    AgentsModule -->|"view content"| Readers
    LLMModule -->|"view content"| Readers
    SciLLModule -->|"view content"| Readers
    SciAgentsModule -->|"view content"| Readers
    Readers -->|"view timeline"| Timeline
    Readers -->|"view assets"| AssetDir

    %% Badge integration
    BadgeService -->|"embed badges"| ReadmeRoot
    BadgeService -->|"embed badges"| AgentsModule
    BadgeService -->|"embed badges"| LLMModule
    BadgeService -->|"embed badges"| SciLLModule
    BadgeService -->|"embed badges"| SciAgentsModule
    ArxivService -->|"embed arXiv links"| ReadmeRoot

    %% Click Events
    click .gitmodules "https://github.com/ur-whitelab/llms-in-science/blob/main//.gitmodules"
    click ReadmeRoot "https://github.com/ur-whitelab/llms-in-science/blob/main//README.md"
    click ContribGuidelines "https://github.com/ur-whitelab/llms-in-science/blob/main//CONTRIBUTING.md"
    click AgentsModule "https://github.com/ur-whitelab/llms-in-science/blob/main//Agents/README.md"
    click LLMModule "https://github.com/ur-whitelab/llms-in-science/blob/main//LLM/README.md"
    click SciLLModule "https://github.com/ur-whitelab/llms-in-science/blob/main//Sci_LLM/README.md"
    click SciAgentsModule "https://github.com/ur-whitelab/llms-in-science/blob/main//Sci_agents/README.md"
    click Timeline "https://github.com/ur-whitelab/llms-in-science/tree/main//LLMTimeline"
    click AssetDir "https://github.com/ur-whitelab/llms-in-science/tree/main//assets"

    %% Styles
    classDef actor fill:#FDEDEC,stroke:#E74C3C;
    classDef cloud fill:#F2F4F4,stroke:#95A5A6,stroke-dasharray: 5, 5;
    classDef external fill:#DFF2BF,stroke:#4F8A10;
    classDef governance fill:#FCF3CF,stroke:#B7950B;
    classDef content fill:#E8F8F5,stroke:#1ABC9C;
    classDef resources fill:#F0F3F4,stroke:#566573;
    classDef service fill:#D6E9FF,stroke:#2B7CE9;
```
