# alexander1022/darwin architecture

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

- Interactive diagram: https://gitdiagram.com/alexander1022/darwin
- Repository: https://github.com/alexander1022/darwin

## Overview

##### Project type and purpose
- Darwin is a Python-based NLP/ML toolkit and conversational dialog trainer for Bulgarian.
- It’s structured as a library/CLI tool rather than a full-stack web app. It ingests dialogues, uses SpaCy (and eventually simplemma) to parse language, manages conversation state, and supports training and evaluation.

##### File structure
- Top-level directories:
- additional/         ← JSON resources (intents, characteristics)
- darwin/             ← core Python package modules
- tests/              ← unit tests for comparison & search logic
- Key modules in darwin/:
- darwin.py           ← entry point / orchestrator
- chatbot.py          ← chat I/O interface
- training.py         ← model-training logic
- context_parser.py   ← dialogue context extraction
- memory_manager.py   ← conversation state storage
- contact_manager.py  ← user/contact data interface
- search.py           ← text-search utility
- comparisons.py      ← intent/entity comparison logic
- tags.py             ← linguistic tagging helpers
- tools.py            ← shared utilities
- Configs & data:
- .env.template       ← environment variables stub
- contacts.csv        ← sample contact data
- additional/*.json   ← intent definitions, Bulgarian characteristics
- Dependencies: defined in requirements.txt (e.g., spaCy).

##### Key insights from README
- Uses SpaCy with a Bulgarian model; future simplemma integration.
- Devised as a Python package installable from source.
- Core functionality: dialogue handling, training conversational models.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Layer"
        JSON1["Bulgarian Characteristics JSON"]:::data
        JSON2["Intents JSON"]:::data
        CSV["Contacts CSV"]:::data
        ENV[".env Template"]:::data
        Req["requirements.txt"]:::data
    end

    subgraph "Preprocessing & NLP"
        Context["Context Parser"]:::processing
        Tags["Linguistic Tagging Helpers"]:::processing
        SpaCy["SpaCy Engine"]:::processing
        Simplemma["Simplemma (future)"]:::processing
    end

    subgraph "Core Logic"
        Memory["Memory Manager"]:::core
        Contact["Contact Manager"]:::core
        Comparisons["Intent/Entity Comparison Logic"]:::core
        Search["Text-Search Utility"]:::core
        Tools["Shared Utilities"]:::core
    end

    subgraph "Orchestrator & Interface"
        Darwin["Darwin CLI Entry"]:::orchestrator
        Chatbot["Chatbot I/O Adapter"]:::orchestrator
    end

    subgraph "Training Module"
        Training["Training Module"]:::aux
    end

    subgraph "Testing"
        TestComp["Comparisons Module Tests"]:::aux
        TestSearch["Search Module Tests"]:::aux
    end

    JSON1 -->|"load intents"| Context
    JSON2 --> Context
    CSV --> Contact
    ENV --> Darwin
    Req --> Darwin

    Context --> Tags
    SpaCy --> Tags
    Simplemma --> Tags

    Context --> Memory
    Context --> Contact
    Tags --> Comparisons
    Comparisons --> Search
    Tools --> Comparisons
    Tools --> Search

    Darwin --> Context
    Darwin --> Memory
    Darwin --> Contact
    Darwin --> Comparisons
    Darwin --> Search
    Darwin --> Training
    Chatbot --> Darwin
    Darwin --> Chatbot

    Training -.->|"save model artifacts"| JSON1

    TestComp --> Comparisons
    TestSearch --> Search

    click JSON1 "https://github.com/alexander1022/darwin/blob/main/additional/bulgarian-characteristics.json"
    click JSON2 "https://github.com/alexander1022/darwin/blob/main/additional/intents.json"
    click CSV "https://github.com/alexander1022/darwin/blob/main/darwin/contacts.csv"
    click ENV "https://github.com/alexander1022/darwin/blob/main/darwin/.env.template"
    click Req "https://github.com/alexander1022/darwin/blob/main/requirements.txt"
    click Context "https://github.com/alexander1022/darwin/blob/main/darwin/context_parser.py"
    click Tags "https://github.com/alexander1022/darwin/blob/main/darwin/tags.py"
    click Memory "https://github.com/alexander1022/darwin/blob/main/darwin/memory_manager.py"
    click Contact "https://github.com/alexander1022/darwin/blob/main/darwin/contact_manager.py"
    click Comparisons "https://github.com/alexander1022/darwin/blob/main/darwin/comparisons.py"
    click Search "https://github.com/alexander1022/darwin/blob/main/darwin/search.py"
    click Tools "https://github.com/alexander1022/darwin/blob/main/darwin/tools.py"
    click Darwin "https://github.com/alexander1022/darwin/blob/main/darwin/darwin.py"
    click Chatbot "https://github.com/alexander1022/darwin/blob/main/darwin/chatbot.py"
    click Training "https://github.com/alexander1022/darwin/blob/main/darwin/training.py"
    click TestComp "https://github.com/alexander1022/darwin/blob/main/tests/comparisons.py"
    click TestSearch "https://github.com/alexander1022/darwin/blob/main/tests/text_search.py"

    classDef data fill:#D0E1F9,stroke:#333,stroke-width:1px
    classDef processing fill:#D5F5E3,stroke:#333,stroke-width:1px
    classDef core fill:#FDEBD0,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#E8DAEF,stroke:#333,stroke-width:1px
    classDef aux fill:#F2F3F4,stroke:#333,stroke-width:1px
```
