# luxshan2000/dravida-kavacham architecture

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

- Interactive diagram: https://gitdiagram.com/luxshan2000/dravida-kavacham
- Repository: https://github.com/luxshan2000/dravida-kavacham

## Overview

##### Project type and purpose
- DravidaKavacham is an open-source Python library (packaged on PyPI) for detecting abusive content in Dravidian languages (Tamil and Malayalam) using a pre-trained PyTorch model.

##### File structure
- Top-level files:
- LICENSE, .gitignore, pyproject.toml → packaging & licensing
- Readme.md, docs/ → user documentation and architecture details
- .github/workflows → CI/CD (lint, test, release)
- Core package folder: dravida_kavacham/
- __init__.py → exposes public API (AbuseDetector)
- model.py → defines the neural network architecture and weight loader
- predictor.py → wraps model inference, exposes predict() method
- utils.py → text preprocessing, tokenization, caching, download utilities
- notebooks/ → exploratory data analysis, demonstration

##### README for additional insights
- Key features: plug-and-play, local model download on first use, customizable extension points
- Dependencies: Python ≥3.10, PyTorch ≥2.2.0
- Usage: instantiate AbuseDetector(), call .predict(text)

a. Main components
1. Client/Application Code (user’s script or notebook)
2. Library Interface (AbuseDetector class in __init__.py)
3. Predictor Module (predictor.py)
4. Model Module (model.py)
5. Utilities Module (utils.py)
6. PyTorch Inference Engine
7. External Storage (model weights repository on PyPI/Hugging Face/remote URL)
b. Relationships & data flows
- The client calls AbuseDetector.predict(text)
- AbuseDetector delegates to Predictor → loads or reuses a Model instance
- Predictor invokes Utils for preprocessing (tokenize, normalize)
- Preprocessed data passed to the Model module
- Model module loads weights via Utils (downloads on first run, caches locally)
- Model performs inference via PyTorch engine
- Predictor postprocesses output (e.g., map logits → labels “Abusive”/“Clean”)
- Result returned to client
c. Architectural patterns & design principles
- Modular separation: interface, preprocessing, model definition, inference
- Lazy initialization and caching pattern: download heavy assets once
- Single Responsibility: each module has clear, minimal responsibilities
d. Key technologies & libraries
- Python packaging: pyproject.toml, setuptools
- PyTorch for neural network inference
- Optional: Hugging Face Hub or raw HTTP for model download
- CI/CD workflows for linting, testing, releases

- Branch into two modules side by side: Predictor and Utils
- Sidebar: show CI/CD pipelines and docs folder as auxiliary infrastructure

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main user interaction
    ClientApp["Client Application Code"]:::external
    ClientApp -->|"calls predict(text)"| Interface

    %% Core Library Layer
    subgraph "Core Library"
        direction TB
        Interface["AbuseDetector (Library Interface)"]:::interface
        Predictor["Predictor Module"]:::processing
        Utils["Utilities Module"]:::processing
        Model["Model Module"]:::processing
        Engine["PyTorch Inference Engine"]:::engine
        PostProcessor["Postprocessor (Logits → Labels)"]:::processing
    end

    Interface -->|"delegates to"| Predictor
    Predictor -->|"preprocess"| Utils
    Predictor -->|"loads/invokes"| Model
    Model -->|"forward pass"| Engine
    Model -->|"download→cache"| Storage
    Engine -->|"raw logits"| Predictor
    Predictor -->|"postprocess"| PostProcessor
    PostProcessor -->|"prediction label"| ClientApp

    %% External Systems
    Storage["External Storage (Model Weights)"]:::external

    %% Auxiliary Infrastructure
    subgraph "Auxiliary Infrastructure"
        direction TB
        Readme["Readme.md"]:::infra
        ArchDocs["docs/Architecture.md"]:::infra
        Packaging["pyproject.toml\nLICENSE"]:::infra
        CI_Lint[".github/workflows/lint.yml"]:::infra
        CI_Test[".github/workflows/test-release.yml"]:::infra
        CI_Release[".github/workflows/release.yml"]:::infra
    end

    %% Click Events
    click ClientApp "https://github.com/luxshan2000/dravida-kavacham/blob/main/notebooks/data_exploration.ipynb"
    click Interface "https://github.com/luxshan2000/dravida-kavacham/blob/main/dravida_kavacham/__init__.py"
    click Predictor "https://github.com/luxshan2000/dravida-kavacham/blob/main/dravida_kavacham/predictor.py"
    click Model "https://github.com/luxshan2000/dravida-kavacham/blob/main/dravida_kavacham/model.py"
    click Utils "https://github.com/luxshan2000/dravida-kavacham/blob/main/dravida_kavacham/utils.py"
    click Readme "https://github.com/luxshan2000/dravida-kavacham/blob/main/Readme.md"
    click ArchDocs "https://github.com/luxshan2000/dravida-kavacham/blob/main/docs/Architecture.md"
    click Packaging "https://github.com/luxshan2000/dravida-kavacham/blob/main/pyproject.toml"
    click Packaging "https://github.com/luxshan2000/dravida-kavacham/tree/main/LICENSE"
    click CI_Lint "https://github.com/luxshan2000/dravida-kavacham/blob/main/.github/workflows/lint.yml"
    click CI_Test "https://github.com/luxshan2000/dravida-kavacham/blob/main/.github/workflows/test-release.yml"
    click CI_Release "https://github.com/luxshan2000/dravida-kavacham/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef interface fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef processing fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef engine fill:#f8d7da,stroke:#333,stroke-width:1px,stroke-dasharray:5 5
    classDef infra fill:#e2e3e5,stroke:#333,stroke-width:1px
```
