# algowizzzz/docasst architecture

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

- Interactive diagram: https://gitdiagram.com/algowizzzz/docasst
- Repository: https://github.com/algowizzzz/docasst

## Overview

##### Project type and purpose
- This is a full-stack “Doc Review Assistant” application:
- Backend: Python Flask app (app/…).
- Frontend: React-based rich-text editor built with Lexical (editor/src/…).
- Storage: Filesystem-based (data/documents, data/uploads) via core/store & core/vfs.
- AI integrations: Claude Vision for PDF→JSON, RiskGPT for chat/Q&A, custom prompt pipelines.

##### File structure
- Top-level directories:
- app/: Flask application – server.py, routes, socketio handlers, auth, config loader.
- core/: Business logic – agents, suggestion engines, chat history, comment model, template processor, virtual FS.
- tools/: Low-level utilities – file I/O, PDF processor (poppler-utils wrapper), LLM client abstractions.
- web/: Jinja2 templates + static CSS/JS for non-SPA pages and legacy views.
- editor/: React+Lexical source & build config – custom editor components, plugins, UI primitives, API clients.
- config/: JSON/YAML definitions of agents, prompts, templates, and user credentials.
- data/: Persists JSON-ified docs and uploaded files.

- Key architectural cues:
- MVC-style Flask server rendering Jinja2 for initial page loads.
- REST+WebSocket (Socket.IO) endpoints for real-time editing and AI suggestions.
- Modular “core” layer keeps business rules separate from transport.
- Editor as a single-page app bundle served by Flask or static files.

##### README insights
- Features call out six-section analysis, AI chat, comments, text improvement.
- Quick-start confirms Flask + Lexical-React build pipeline + poppler for PDF.

- User Browser (UI)
- Frontend Editor (React/Lexical bundle)
- Flask Backend
- Core Services
- Tooling Modules
- Filesystem Storage
- External AI Services

b. Relationships and interactions:
- Browser → Editor bundle (served via Flask static route)
- Editor ←→ Flask WebSocket (Socket.IO) for live edits & AI prompts
- Flask REST API endpoints → Core Services (agent.py, ai_suggestions, chat_history)
- Core Services → Tools (pdf_processor, llm_client) → External AI APIs (Anthropic/Claude, RiskGPT)
- Core Services → Filesystem (via core/store & core/vfs) for document persistence
- Flask → Jinja2 Templates (web/templates) for non-editor pages (login, settings)

c. Architectural patterns/design principles:
- Layered architecture: Transport (app/routes) → Business Logic (core) → Persistence (data/)
- Plugin/agent pattern in core for extensibility of analysis phases
- Real-time event-driven editing via Socket.IO
- Clear separation of concerns:
– app/ handles HTTP & auth
– core/ implements domain logic
– tools/ manage 3rd-party integrations

d. Key technologies/frameworks:
- Python, Flask, Flask-SocketIO, Jinja2
- Node.js, React, Lexical Editor
- poppler-utils for PDF parsing
- JSON/YAML configuration
- Socket.IO for real-time comms
- External LLM APIs (Claude Vision, RiskGPT)

##### Detail
- Sub-components where relevant (e.g., within Core Services, show agent.py vs chat_history vs template_processor).
- WebSocket handler as a distinct element under app/socketio_handlers.py.
- Build step: editor/src → build → served static assets.
- Don’t over-compartmentalize beyond logical layers, but separate each folder as a component.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "User Interface" 
        direction TB
        Browser["User Browser"]:::frontend
        Editor["React/Lexical Editor"]:::frontend
    end

    %% Backend Layer
    subgraph "Flask Backend (HTTP & WebSocket Layer)" 
        direction TB
        Server["server.py"]:::backend
        AuthRoutes["auth_routes.py"]:::backend
        DocRoutes["doc_review_routes.py"]:::backend
        SocketHandlers["socketio_handlers.py"]:::backend
        AuthModule["auth.py"]:::backend
        ConfigLoader["config.py"]:::backend
    end

    %% Core Services
    subgraph "Core Business Logic Services"
        direction TB
        Agent["agent.py"]:::backend
        AISuggestions["ai_suggestions.py"]:::backend
        ChatHistory["chat_history.py"]:::backend
        Comments["comments.py"]:::backend
        Models["models.py"]:::backend
        TemplateProcessor["template_processor.py"]:::backend

        subgraph "RiskGPT Integration (Core Plugin)"
            direction TB
            RGInit["__init__.py"]:::backend
            RGNodes["nodes.py"]:::backend
            RGSchemas["schemas.py"]:::backend
            RGPTAgent["riskgpt_agent.py"]:::backend
            RGPTNodes["riskgpt_nodes.py"]:::backend
            RGPTSchemas["riskgpt_schemas.py"]:::backend
        end
    end

    %% Tools Layer
    subgraph "Utilities & Tools"
        direction TB
        PDFProc["pdf_processor.py"]:::tools
        LLMClient["llm_client.py"]:::tools
        FileUtils["file_utils.py"]:::tools
    end

    %% Storage Layer
    subgraph "Filesystem Storage" 
        direction TB
        Store["store.py"]:::storage
        VFS["vfs.py"]:::storage
        Documents["data/documents/"]:::storage
        Uploads["data/uploads/"]:::storage
    end

    %% Config Layer
    subgraph "Configuration Definitions"
        direction TB
        ConfigExample["config.example.yaml"]:::config
        UsersConfig["users.json"]:::config
        AgentConfig["doc_review_agent.json"]:::config
        Prompts["prompts/"]:::config
        TemplatesConfig["outline_templates/policy_template.json"]:::config
    end

    %% Legacy / Non-SPA Pages
    subgraph "Jinja2 Templates & Static Pages"
        direction TB
        Templates["web/templates/*.html"]:::legacy
        CSS["web/static/css/*.css"]:::legacy
        JS["web/static/js/*.js"]:::legacy
        EditorIIFE["editor.iife.js"]:::legacy
    end

    %% External AI Services
    subgraph "External AI APIs"
        direction TB
        ClaudeVision["Claude Vision API"]:::cloud
        RiskGPTAPI["RiskGPT API"]:::cloud
    end

    %% Connections
    Browser -->|"loads bundle"| Editor
    Editor -->|"HTTP REST /socket.io"| Server
    Editor <-->|"WebSocket"| SocketHandlers
    Server -->|"invokes routes"| AuthRoutes
    Server -->|"invokes routes"| DocRoutes
    Server -->|"uses"| AuthModule
    Server -->|"loads config"| ConfigLoader
    Server -->|"renders"| Templates
    AuthRoutes -->|POST/GET| Agent
    DocRoutes -->|POST/GET| AISuggestions
    DocRoutes -->|POST/GET| ChatHistory
    DocRoutes -->|POST/GET| Comments
    DocRoutes -->|POST/GET| TemplateProcessor
    Agent -->|calls| RGInit
    Agent -->|calls| RGPTAgent
    AISuggestions -->|calls| LLMClient
    ChatHistory -->|calls| Store
    Comments -->|calls| VFS
    TemplateProcessor -->|reads| TemplatesConfig
    Agent -->|calls| PDFProc
    PDFProc -->|processes PDF| Store
    LLMClient -->|API calls| ClaudeVision
    LLMClient -->|API calls| RiskGPTAPI
    Agent -->|persists| Documents
    Agent -->|persists| Uploads

    %% Click Events
    click Server "https://github.com/algowizzzz/docasst/blob/main/app/server.py"
    click AuthRoutes "https://github.com/algowizzzz/docasst/blob/main/app/routes/auth_routes.py"
    click DocRoutes "https://github.com/algowizzzz/docasst/blob/main/app/routes/doc_review_routes.py"
    click SocketHandlers "https://github.com/algowizzzz/docasst/blob/main/app/socketio_handlers.py"
    click AuthModule "https://github.com/algowizzzz/docasst/blob/main/app/auth.py"
    click ConfigLoader "https://github.com/algowizzzz/docasst/blob/main/app/config.py"
    click Agent "https://github.com/algowizzzz/docasst/blob/main/core/agent.py"
    click AISuggestions "https://github.com/algowizzzz/docasst/blob/main/core/ai_suggestions.py"
    click ChatHistory "https://github.com/algowizzzz/docasst/blob/main/core/chat_history.py"
    click Comments "https://github.com/algowizzzz/docasst/blob/main/core/comments.py"
    click Models "https://github.com/algowizzzz/docasst/blob/main/core/models.py"
    click TemplateProcessor "https://github.com/algowizzzz/docasst/blob/main/core/template_processor.py"
    click RGInit "https://github.com/algowizzzz/docasst/blob/main/core/riskgpt/__init__.py"
    click RGNodes "https://github.com/algowizzzz/docasst/blob/main/core/riskgpt/nodes.py"
    click RGSchemas "https://github.com/algowizzzz/docasst/blob/main/core/riskgpt/schemas.py"
    click RGPTAgent "https://github.com/algowizzzz/docasst/blob/main/core/riskgpt_agent.py"
    click RGPTNodes "https://github.com/algowizzzz/docasst/blob/main/core/riskgpt_nodes.py"
    click RGPTSchemas "https://github.com/algowizzzz/docasst/blob/main/core/riskgpt_schemas.py"
    click Store "https://github.com/algowizzzz/docasst/blob/main/core/store.py"
    click VFS "https://github.com/algowizzzz/docasst/blob/main/core/vfs.py"
    click Documents "https://github.com/algowizzzz/docasst/tree/main/data/documents/"
    click Uploads "https://github.com/algowizzzz/docasst/tree/main/data/uploads/"
    click PDFProc "https://github.com/algowizzzz/docasst/blob/main/tools/pdf_processor.py"
    click LLMClient "https://github.com/algowizzzz/docasst/blob/main/tools/llm_client.py"
    click FileUtils "https://github.com/algowizzzz/docasst/blob/main/tools/file_utils.py"
    click Editor "https://github.com/algowizzzz/docasst/blob/main/editor/package.json"
    click ConfigExample "https://github.com/algowizzzz/docasst/blob/main/config/config.example.yaml"
    click UsersConfig "https://github.com/algowizzzz/docasst/blob/main/config/users.json"
    click AgentConfig "https://github.com/algowizzzz/docasst/blob/main/config/agent/doc_review_agent.json"
    click Prompts "https://github.com/algowizzzz/docasst/tree/main/config/prompts/"
    click TemplatesConfig "https://github.com/algowizzzz/docasst/blob/main/config/doc_review/outline_templates/policy_template.json"
    click Templates "https://github.com/algowizzzz/docasst/blob/main/web/templates/*.html"
    click CSS "https://github.com/algowizzzz/docasst/blob/main/web/static/css/*.css"
    click JS "https://github.com/algowizzzz/docasst/blob/main/web/static/js/*.js"
    click EditorIIFE "https://github.com/algowizzzz/docasst/blob/main/web/static/editor/editor.iife.js"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef cloud fill:#F0F8FF,stroke:#333,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef tools fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef legacy fill:#E0E0E0,stroke:#333,stroke-width:1px
```
