# mwasifanwar/legalmind architecture

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

- Interactive diagram: https://gitdiagram.com/mwasifanwar/legalmind
- Repository: https://github.com/mwasifanwar/legalmind

## Overview

##### Project type and purpose
- LegalMind is a specialized back-end NLP system (no UI code is present) that:
- Ingests and preprocesses legal documents
- Trains and applies transformer-based models to classify clauses, check compliance, detect risks, and generate summaries
- Exposes a RESTful API to serve analyses

##### File structure
Top-level directories and roles:
- api/
– server.py, init.py — defines the HTTP endpoints and runs the API server (likely Flask/FastAPI)
- config/
– app_config.yaml, model_config.yaml — centralize hyperparameters, paths, credentials
- data/
– dataloader.py, preprocessing.py — data ingestion, cleaning, and preparation
- core/
– contract_analyzer.py, risk_detector.py, summary_generator.py, document_processor.py — orchestrate pipeline steps using models
- models/
– legal_bert.py (wrapper for HuggingFace transformer), clause_classifier.py, compliance_checker.py — model definitions and inference logic
- training/
– trainers.py — training loops, metrics logging
- utils/
– config.py, helpers.py, text_processor.py, visualization.py — shared utilities for parsing, plotting, config loading
- main.py & run_api.py — entry points for CLI orchestration versus API launch
- requirements.txt — Python dependencies

##### README for additional insights
- Project is transformer-based (“legal AI”) and focuses on compliance risk, clause classification, summarization.

a. Main Components
1. Data Ingestion & Preprocessing (data/)
2. Model Training (training/ + models/)
3. Inference Pipeline (core/ + models/)
4. Configuration Management (config/)
5. API Layer (api/ + run_api.py)
6. Utilities & Helpers (utils/)
7. External Dependencies:
- Transformer model weights (e.g., from HuggingFace)
- Storage (S3 or local file system for datasets and model artifacts)
- Logging/Monitoring (optional)

b. Relationships & Interactions
- Data flows from raw sources → data.dataloader → data.preprocessing → preprocessed data.
- Training module picks up preprocessed data → training.trainers → produces model artifacts in “models/”.
- Core pipeline loads configs (config/) and model artifacts → core.document_processor applies models for clause classification, compliance_checker, risk_detector, summary_generator.
- API server imports core.contract_analyzer and exposes endpoints.
- utils provide cross-cutting functions (config loader, text cleaning, visualization).

c. Architectural Patterns & Principles
- Modular layering: Data → Training → Core/Inference → API
- Separation of concerns: distinct packages for data, training, inference, serving
- Configuration as code: all parameters in config/ YAML files, loaded via utils/config.py
- Dependency injection: API server configured with core components at startup

d. Key Technologies & Frameworks
- Python 3.x
- HuggingFace transformers (wrapped in models/legal_bert.py)
- FastAPI or Flask (api/server.py)
- PyTorch or TensorFlow (in training/trainer)
- YAML for configuration

##### Diagramming recommendations
– Raw Data → Data Preprocessor → Preprocessed Data Store
– Preprocessed Data → Trainer → Model Artifacts
– API Request → Core Analyzer → Model Inference → API Response

##### Capturing essential architectural elements
- Configuration service as its own component, feeding all others

## Diagram (Mermaid)

```mermaid
graph TB
    %% Data Layer
    subgraph "Data Layer"
        Dataloader["dataloader.py"]:::code
        Preprocessing["preprocessing.py"]:::code
    end
    RawData["Raw Data Source"]:::external
    PreprocessedData["Preprocessed Data Store"]:::storage

    RawData -->|"raw text"| Dataloader
    Dataloader -->|"dataframes"| Preprocessing
    Preprocessing -->|"cleaned data"| PreprocessedData

    %% Training Layer
    subgraph "Training"
        Trainer["trainers.py"]:::training
        ModelArtifacts["Model Artifacts"]:::storage
    end

    PreprocessedData -->|"training data"| Trainer
    Trainer -->|"model files"| ModelArtifacts

    %% Model Definitions
    subgraph "Model Definitions & Inference Logic"
        LegalBERT["legal_bert.py"]:::code
        ClauseClassifier["clause_classifier.py"]:::code
        ComplianceChecker["compliance_checker.py"]:::code
    end

    ModelArtifacts -->|"loads artifacts"| LegalBERT
    ModelArtifacts -->|"loads artifacts"| ClauseClassifier
    ModelArtifacts -->|"loads artifacts"| ComplianceChecker

    %% Core Inference Pipeline
    subgraph "Core Pipeline"
        DocumentProcessor["document_processor.py"]:::code
        ContractAnalyzer["contract_analyzer.py"]:::code
        RiskDetector["risk_detector.py"]:::code
        SummaryGenerator["summary_generator.py"]:::code
    end

    LegalBERT -->|"embeddings"| DocumentProcessor
    ClauseClassifier -->|"classification"| DocumentProcessor
    ComplianceChecker -->|"compliance checks"| DocumentProcessor
    DocumentProcessor --> ContractAnalyzer
    ContractAnalyzer --> RiskDetector
    RiskDetector --> SummaryGenerator

    %% API Layer
    subgraph "API Layer"
        InitAPI["__init__.py"]:::code
        APIServer["server.py"]:::code
        RunAPI["run_api.py"]:::code
    end

    SummaryGenerator -->|"results"| APIServer
    APIServer -->|"JSON response"| Client["API Client"]:::external
    RunAPI --> APIServer

    %% Configuration Management
    subgraph "Configuration Management"
        InitConfig["__init__.py"]:::config
        AppConfig["app_config.yaml"]:::config
        ModelConfig["model_config.yaml"]:::config
        ConfigLoader["config.py"]:::code
    end

    ConfigLoader --> AppConfig
    ConfigLoader --> ModelConfig
    ConfigLoader --> Dataloader
    ConfigLoader --> Preprocessing
    ConfigLoader --> Trainer
    ConfigLoader --> DocumentProcessor
    ConfigLoader --> APIServer

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
        InitUtils["__init__.py"]:::code
        Helpers["helpers.py"]:::code
        TextProcessor["text_processor.py"]:::code
        Visualization["visualization.py"]:::code
    end

    Helpers --> Dataloader
    Helpers --> Preprocessing
    Helpers --> DocumentProcessor
    Helpers --> Trainer
    Helpers --> APIServer
    TextProcessor --> Dataloader
    Visualization --> Trainer

    %% External Dependencies
    TransformerHub["HuggingFace Model Hub"]:::external
    StorageService["S3 / Local FS"]:::external

    TransformerHub --> ModelArtifacts
    StorageService --> RawData
    StorageService --> ModelArtifacts

    %% Click Events
    click Dataloader "https://github.com/mwasifanwar/legalmind/blob/main/data/dataloader.py"
    click Preprocessing "https://github.com/mwasifanwar/legalmind/blob/main/data/preprocessing.py"
    click LegalBERT "https://github.com/mwasifanwar/legalmind/blob/main/models/legal_bert.py"
    click ClauseClassifier "https://github.com/mwasifanwar/legalmind/blob/main/models/clause_classifier.py"
    click ComplianceChecker "https://github.com/mwasifanwar/legalmind/blob/main/models/compliance_checker.py"
    click Trainer "https://github.com/mwasifanwar/legalmind/blob/main/training/trainers.py"
    click DocumentProcessor "https://github.com/mwasifanwar/legalmind/blob/main/core/document_processor.py"
    click ContractAnalyzer "https://github.com/mwasifanwar/legalmind/blob/main/core/contract_analyzer.py"
    click RiskDetector "https://github.com/mwasifanwar/legalmind/blob/main/core/risk_detector.py"
    click SummaryGenerator "https://github.com/mwasifanwar/legalmind/blob/main/core/summary_generator.py"
    click APIServer "https://github.com/mwasifanwar/legalmind/blob/main/api/server.py"
    click InitAPI "https://github.com/mwasifanwar/legalmind/blob/main/api/__init__.py"
    click RunAPI "https://github.com/mwasifanwar/legalmind/blob/main/run_api.py"
    click AppConfig "https://github.com/mwasifanwar/legalmind/blob/main/config/app_config.yaml"
    click ModelConfig "https://github.com/mwasifanwar/legalmind/blob/main/config/model_config.yaml"
    click InitConfig "https://github.com/mwasifanwar/legalmind/blob/main/config/__init__.py"
    click ConfigLoader "https://github.com/mwasifanwar/legalmind/blob/main/utils/config.py"
    click Helpers "https://github.com/mwasifanwar/legalmind/blob/main/utils/helpers.py"
    click TextProcessor "https://github.com/mwasifanwar/legalmind/blob/main/utils/text_processor.py"
    click Visualization "https://github.com/mwasifanwar/legalmind/blob/main/utils/visualization.py"
    click InitUtils "https://github.com/mwasifanwar/legalmind/blob/main/utils/__init__.py"

    %% Styles
    classDef code fill:#cce5ff,stroke:#004085,color:#004085
    classDef storage fill:#d4edda,stroke:#155724,color:#155724
    classDef training fill:#fff3cd,stroke:#856404,color:#856404
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24
```
