# maggieappleton/lodestone architecture

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

- Interactive diagram: https://gitdiagram.com/maggieappleton/lodestone
- Repository: https://github.com/maggieappleton/lodestone

## Overview

##### Project Type and Purpose
- Lodestone V1 is clearly a frontend-centric application built with React and TypeScript, using Vite for bundling, Tailwind for styling, and Dexie for local (likely IndexedDB) storage.
- The project leverages several libraries and frameworks: Remirror (rich text editing), Dexie (client-side database), Tailwind (CSS), Vite (development/build tool), and React.
- It also appears to have an evaluation component with prompts, test cases, and multiple models (Anthropic and OpenAI) integration, along with dynamic questions and annotation services. This suggests the application might be designed for interactive, dynamic content creation, evaluation, or argument mapping.

##### Analyzing the File Structure
- Top-Level Files/Directories: Files like index.html, package.json, vite.config.ts, and configuration files (esLint, PostCSS, Tailwind, and tsconfig) give an immediate context of a Vite-based React application.
- src Directory: This is the main source folder where most business logic, UI components, and services reside.
- Pages are defined under src/pages (e.g., EditorPage, EvalPage, InputPage, SessionsPage) which indicate different views/routes.
- Components nested in src/components (e.g., ArgumentGraph, ClaimCard, ClaimsView, DynamicQuestionsPanel, Editor) provide UI/interaction elements.
- Hooks in src/hooks (state management for analysis, dynamic questions, session management) provide custom logic linking UI components to the overall application state.
- Services in src/services comprise:
- Annotation services (including integrations with external tools like HuggingFace).
- Dynamic questions handling.
- Models integration with Anthropic and OpenAI.
- Evaluation-related aspects are organized in src/evals (containing outputs, prompts, and test cases) which shows a design for interfacing with evaluation flows.
- Utilities (under src/utils) help in handling text processing, session management, highlighting operations, etc.
- Other folders such as public and specs hint at static assets and documentation/specifications about argument visualization and dynamic questions.

a. Main Components to Include:
- UI/Client Layer:
- The base HTML (index.html) and root component (main.tsx / App.tsx) that initiates rendering.
- Pages (EditorPage, EvalPage, InputPage, SessionsPage) representing different routes/views.
- Reusable UI components (e.g., ArgumentGraph, ClaimCard, DynamicQuestionsPanel, etc.).
- Application State & Logic:
- Hooks (useAnalysis, useDynamicQuestions, useSessionManager) which govern the application’s state and coordinate component interactions.
- Utilities (textUtils, sessionManager, highlight operations, etc.) which provide supporting functions.
- Business Services:
- Annotation Services: Components interacting with external annotation APIs (e.g., HuggingFace) and internal document utilities.
- Models Services: Abstractions for integrating with different language model APIs (Anthropic, OpenAI).
- Dynamic questions service: Handling logic for dynamic interactions.
- Evaluation Module:
- Evaluation flows organized through prompts, test cases, output management (see src/evals). This illustrates how the system handles evaluation and assessments.
- Data Storage:
- Dexie integration (via src/db.ts) suggesting IndexedDB usage on the client for local data persistence.
- Configuration and Build Tools:
- Vite, Tailwind, and other configuration files to manage development and production settings.

b. Relationships and Data Flow:
- Starting from the Initialization: index.html loads main.tsx which then renders App.tsx.
- The App component routes or determines which Page (Editor/Eval/Input/Sessions) to show based on the user interaction.
- UI Components on each page trigger state changes managed by Hooks. These hooks then call Services (like annotation or dynamic questions) to process data or interact with external APIs.
- The Services layer communicates with both evaluated outputs (from the evaluation module) and local storage (through Dexie).
- Utilities support data transformation, ensuring that outputs from services are formatted for display.

c. Architectural Patterns and Design Principles:
- Component-Based Architecture: Clear separation of concerns with components, pages, hooks, and services.
- Separation of Concerns: UI logic is separated from business logic and data management.
- Modular and Scalable Design: The evaluation components with dedicated test cases, prompts, and outputs indicate a design prepared for extensibility.
- Integration with External Services: Annotation and model service integration denote a design mindful of external dependencies.

d. Relevant Technologies:
- React & TypeScript: For the component and type-safe development.
- Vite: As the bundler and development server.
- Tailwind CSS: For styling and UI responsiveness.
- Remirror: Likely used in the Editor component for rich text editing.
- Dexie: For client-side database handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI/Client Layer Subgraph
    subgraph "UI/Client Layer"
        UI1["index.html"]:::ui
        UI2["src/main.tsx"]:::ui
        UI3["src/App.tsx"]:::ui
        UI4["Pages (src/pages)"]:::ui
        UI5["Reusable Components (src/components)"]:::ui
    end

    %% Application State & Logic Subgraph
    subgraph "Application State & Logic"
        AS1["Custom Hooks (src/hooks)"]:::state
        AS2["Utilities (src/utils)"]:::state
    end

    %% Business Services Subgraph
    subgraph "Business Services"
        BS1["Annotation Services (src/services/annotation)"]:::service
        BS2["Dynamic Questions Service (src/services/dynamicQuestions.ts)"]:::service
        BS3["Models Services (src/services/models)"]:::service
    end

    %% Evaluation Module Subgraph
    subgraph "Evaluation Module"
        EV1["Prompts (src/evals/prompts)"]:::eval
        EV2["TestCases (src/evals/testCases)"]:::eval
        EV3["Outputs (src/evals)"]:::eval
    end

    %% Data Storage
    DS["Dexie (src/db.ts)"]:::db

    %% Connections - UI Initialization
    UI1 -->|"loads"| UI2
    UI2 -->|"boots"| UI3
    UI3 -->|"routes to"| UI4
    UI3 -->|"renders"| UI5

    %% Connections - UI to Application State
    UI3 -->|"triggers"| AS1
    UI3 -->|"uses"| AS2

    %% Connections - State to Business Services
    AS1 -->|"calls"| BS1
    AS1 -->|"calls"| BS2
    AS1 -->|"calls"| BS3
    AS2 -->|"supports"| BS1
    AS2 -->|"supports"| BS2
    AS2 -->|"supports"| BS3

    %% Connections - Business Services to Evaluation Module and Data Storage
    BS1 -->|"obtains"| EV1
    BS1 -->|"obtains"| EV2
    BS1 -->|"obtains"| EV3
    BS2 -->|"obtains"| EV1
    BS2 -->|"obtains"| EV2
    BS2 -->|"obtains"| EV3
    BS3 -->|"obtains"| EV1
    BS3 -->|"obtains"| EV2
    BS3 -->|"obtains"| EV3

    BS1 -->|"persists"| DS
    BS2 -->|"persists"| DS
    BS3 -->|"persists"| DS

    %% Legend
    classDef ui fill:#ACE7FF,stroke:#333,stroke-width:2px;
    classDef state fill:#C0FFC0,stroke:#333,stroke-width:2px;
    classDef service fill:#FFDDAC,stroke:#333,stroke-width:2px;
    classDef eval fill:#FFF79A,stroke:#333,stroke-width:2px;
    classDef db fill:#FFD1DC,stroke:#333,stroke-width:2px;

    %% Click Events: UI/Client Layer
    click UI1 "https://github.com/maggieappleton/lodestone/blob/main/index.html"
    click UI2 "https://github.com/maggieappleton/lodestone/blob/main/src/main.tsx"
    click UI3 "https://github.com/maggieappleton/lodestone/blob/main/src/App.tsx"
    click UI4 "https://github.com/maggieappleton/lodestone/tree/main/src/pages"
    click UI5 "https://github.com/maggieappleton/lodestone/tree/main/src/components"

    %% Click Events: Application State & Logic
    click AS1 "https://github.com/maggieappleton/lodestone/tree/main/src/hooks"
    click AS2 "https://github.com/maggieappleton/lodestone/tree/main/src/utils"

    %% Click Events: Business Services
    click BS1 "https://github.com/maggieappleton/lodestone/tree/main/src/services/annotation"
    click BS2 "https://github.com/maggieappleton/lodestone/blob/main/src/services/dynamicQuestions.ts"
    click BS3 "https://github.com/maggieappleton/lodestone/tree/main/src/services/models"

    %% Click Events: Evaluation Module
    click EV1 "https://github.com/maggieappleton/lodestone/tree/main/src/evals/prompts"
    click EV2 "https://github.com/maggieappleton/lodestone/tree/main/src/evals/testCases"
    click EV3 "https://github.com/maggieappleton/lodestone/tree/main/src/evals"

    %% Click Event: Data Storage
    click DS "https://github.com/maggieappleton/lodestone/blob/main/src/db.ts"
```
