# akhilathuluri/readmaster-ai architecture

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

- Interactive diagram: https://gitdiagram.com/akhilathuluri/readmaster-ai
- Repository: https://github.com/akhilathuluri/readmaster-ai

## Overview

##### Project type and purpose
- ReadMaster AI is a single‐page, client-side web application (no dedicated backend in the repo).
- It’s built in React + TypeScript and serves as an Intelligent Markdown Editor with AI-powered writing and analysis features.

##### File structure
- Top-level files:
– index.html, vite.config.ts, tsconfig*.json, tailwind.config.js (build/deploy config)
– package.json, package-lock.json (dependency & script definitions)
- src/: Core of the application
– src/main.tsx + src/index.css: Bootstraps the React app with Vite + global styles
– src/pages/: Route-level pages (LandingPage.tsx, EditorPage.tsx)
– src/components/: UI building blocks (Editor, Preview, Toolbar, AIPanel, WordStatsPanel, SmartSuggestions, etc.)
– src/hooks/: Custom hooks (useVersionManager.ts) for features like version history
– src/store/: Tiny “store” modules (editorStore, settingsStore, versionStore) implementing global state via hooks
– src/services/: External‐facing APIs (ai.ts wraps calls to the AI service)
– src/utils/: Pure helper functions (codeExecutor, contentAnalyzer, export, wordStats, etc.)
- Configuration files for linting (eslint.config.js), styling (postcss.config.js), and environment types (vite-env.d.ts)

##### README for architectural insights
- The “Technical Architecture” section confirms:
– Frontend only (React/TS + React Router)
– Custom hook–based state management
– Tailwind CSS for styling
– AI Integration (calls out to an external AI API)
– In-editor code execution (browser sandbox)

a. Browser/client
– Loads static assets (index.html, JS bundle, CSS) via Vite
– Renders React SPA
b. Pages & Routes
– LandingPage (marketing)
– EditorPage (core UI)
c. UI Components (inside EditorPage)
– Editor (Markdown input + syntax highlighting)
– Preview (live HTML render)
– Toolbar (actions: theme toggle, export, AI toggles)
– AIPanel (smart suggestions, SEO/readability analysis)
– WordStatsPanel (stats, word cloud, reading time)
– CodeExecutor (runs JS in‐browser)
d. State Management
– editorStore: holds current Markdown content, selection
– settingsStore: theme, preferences
– versionStore: version history, undo/redo
e. Services & Utils
– ai.ts → External AI API (REACT_APP_AI_API_KEY)
– codeExecutor.ts → in-browser JS sandbox
– various analyzers & formatters in utils/
f. External Dependencies
– AI Provider (OpenAI or similar) over HTTPS

##### Architectural patterns & design principles
- Component-based hierarchy (presentational vs. container)
- Unidirectional data flow: user action → store update → component render
- Separation of concerns: UI (components) / business logic (services & utils) / state (stores & hooks)
- Client-side only – no server component, all processing (analysis, code execution) done in browser, aside from AI calls

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Static Assets
    StaticAssets["Static Assets<br/>(index.html, JS bundle, CSS)"]:::external

    %% Router
    Router["React Router"]:::frontend

    StaticAssets --> Router

    %% Pages & Routes
    subgraph "Pages & Routes"
        LandingPage["LandingPage"]:::frontend
        EditorPage["EditorPage"]:::frontend
    end

    Router --> LandingPage
    Router --> EditorPage

    %% Core UI Components
    subgraph "EditorPage Components" 
        Editor["Editor"]:::frontend
        Preview["Preview"]:::frontend
        Toolbar["Toolbar"]:::frontend
        AIPanel["AIPanel"]:::frontend
        WordStatsPanel["WordStatsPanel"]:::frontend
        SmartSuggestions["SmartSuggestions"]:::frontend
        CodeExecutor["CodeExecutor"]:::frontend
    end

    EditorPage --> Editor
    EditorPage --> Preview
    EditorPage --> Toolbar
    EditorPage --> AIPanel
    EditorPage --> WordStatsPanel
    EditorPage --> CodeExecutor

    %% AI-powered inline suggestions
    AIPanel --> SmartSuggestions

    %% State Stores
    subgraph "State Stores" 
        editorStore["editorStore"]:::store
        settingsStore["settingsStore"]:::store
        versionStore["versionStore"]:::store
    end

    Editor --> editorStore
    Toolbar --> settingsStore
    Toolbar --> versionStore
    AIPanel --> editorStore
    Preview --> editorStore
    WordStatsPanel --> editorStore

    editorStore --> Editor
    settingsStore --> Toolbar
    versionStore --> Toolbar

    %% Services & Utils
    subgraph "Services & Utilities"
        AIService["AI Service (ai.ts)"]:::service
        CodeExecUtil["Code Executor Util"]:::service
        ContentAnalyzer["Content Analyzer"]:::service
        ExportUtil["Export Utility"]:::service
        WordStatsUtil["Word Stats Utility"]:::service
    end

    AIPanel --> AIService
    CodeExecutor --> CodeExecUtil
    AIPanel --> ContentAnalyzer
    Toolbar --> ExportUtil
    WordStatsPanel --> WordStatsUtil

    %% External AI API
    ExternalAI["External AI API"]:::external
    AIService --> ExternalAI

    %% Click Events
    click LandingPage "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/pages/LandingPage.tsx"
    click LandingPage "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/components/LandingPage.tsx"
    click EditorPage "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/pages/EditorPage.tsx"
    click EditorPage "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/components/EditorPage.tsx"
    click Editor "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/components/Editor.tsx"
    click Preview "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/components/Preview.tsx"
    click Toolbar "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/components/Toolbar.tsx"
    click AIPanel "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/components/AIPanel.tsx"
    click WordStatsPanel "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/components/WordStatsPanel.tsx"
    click SmartSuggestions "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/components/SmartSuggestions.tsx"
    click CodeExecutor "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/components/CodeExecutor.tsx"
    click CodeExecUtil "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/utils/codeExecutor.ts"
    click editorStore "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/store/editorStore.ts"
    click settingsStore "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/store/settingsStore.ts"
    click versionStore "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/store/versionStore.ts"
    click versionStore "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/hooks/useVersionManager.ts"
    click AIService "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/services/ai.ts"
    click ContentAnalyzer "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/utils/contentAnalyzer.ts"
    click ExportUtil "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/utils/export.ts"
    click WordStatsUtil "https://github.com/akhilathuluri/readmaster-ai/blob/main/src/utils/wordStats.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef store fill:#DFFFE0,stroke:#2F8F00,stroke-width:1px
    classDef service fill:#FFE8B0,stroke:#D28C00,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#808080,stroke-width:1px
```
