# gimchedli/zeeguu architecture

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

- Interactive diagram: https://gitdiagram.com/gimchedli/zeeguu
- Repository: https://github.com/gimchedli/zeeguu

## Overview

##### Project type and purpose
- This is a server-side, full-stack (API-centric) Python application (“zeeguu”) providing a RESTful backend for a language-learning platform.
- The README only gives the name, but the file tree shows:
- An API layer (Flask apps and endpoints)
- A rich “core” layer implementing content retrieval, cleaning, recommendation, behavioral modeling, scheduling, NLP pipelines, ML models, emailer, YouTube integration, etc.
- A data layer (models, SQL queries, Elasticsearch integration)
- Various utilities, configs, and tests.

##### File structure
- Top-level:
- api/ – Flask applications (app.py, cross_domain_app.py), endpoint modules, helper wrappers, tests
- core/ – domain logic subdivided by functionality (account_management, content_retriever, content_recommender, behavioral_modeling, NLP pipelines, ML models, scheduling, user statistics, etc.)
- config/ – loader for environment and settings
- cl/ – command-line entry points (if any)
- logging/ – logging configuration
- Notice common patterns:
- MVC-inspired: api = controllers/routes, core = services/business logic, core/model & core/sql = persistence
- External integrations: feed handlers, YouTube API, Elasticsearch, GEC tagger, spacy, tokenizer wrappers
- Configuration loader abstracts environment variables and secrets

##### README
- Python 3.x, Flask
- PostgreSQL or similar (SQL queries under core/sql)
- Elasticsearch (“core/elastic” and “core/semantic_search”)
- ML joblib models
- External NLP libraries (spaCy, stanza)
- RSS/newspaper content retrieval
- Email notifications
- YouTube API calls

##### Final advice
- Keep labels concise and consistent with package names.
- Use layering visually: horizontal tiers for presentation, application, domain logic, and data.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients"
        WebClient["Web Client"]:::client
        MobileClient["Mobile Client"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        APIApp["Flask API Gateway"]:::api
        AccountsEP["Accounts Endpoint"]:::api
        ExercisesEP["Exercises Endpoint"]:::api
        ExerciseSessionsEP["Exercise Sessions Endpoint"]:::api
        NotificationsEP["Notifications Endpoint"]:::api
        UserVideoEP["User Video Endpoint"]:::api
        WatchingSessionEP["User Watching Session Endpoint"]:::api
    end

    %% Core Services
    subgraph "Core Services"
        AccountMgmt["Account Management Service"]:::service
        ContentRetriever["Content Retriever Service"]:::service
        ContentCleaner["Content Cleaner & Parser Service"]:::service
        Recommender["Content Recommender Service"]:::service
        NLPML["NLP Pipeline & ML Models"]:::service
        ExSessionMgmt["Exercise & Session Management Service"]:::service
        BehaviorSched["Behavioral Modeling & Scheduling Service"]:::service
        Emailer["Emailer & Notification Service"]:::service
        YouTubeInt["YouTube Integration Service"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        RelationalDB["Relational Database"]:::datastore
        Elastic["Elasticsearch Cluster"]:::datastore
    end

    %% External Integrations
    subgraph "External Integrations"
        Feeds["RSS/Newspaper Feeds"]:::external
        YouTubeAPI["YouTube Data API"]:::external
        NLPServers["spaCy/Stanza"]:::external
        SMTP["SMTP Server"]:::external
    end

    %% Connections
    WebClient -->|requests| APIApp
    MobileClient -->|requests| APIApp

    APIApp -->|routes to| AccountsEP
    APIApp -->|routes to| ExercisesEP
    APIApp -->|routes to| ExerciseSessionsEP
    APIApp -->|routes to| NotificationsEP
    APIApp -->|routes to| UserVideoEP
    APIApp -->|routes to| WatchingSessionEP

    AccountsEP -->|manages| AccountMgmt
    ExercisesEP -->|handles| ExSessionMgmt
    ExerciseSessionsEP -->|handles| ExSessionMgmt
    NotificationsEP -->|sends via| Emailer
    UserVideoEP -->|manages| YouTubeInt
    WatchingSessionEP -->|records| YouTubeInt

    AccountMgmt -->|reads/writes| RelationalDB

    ContentRetriever -->|fetches from| Feeds
    ContentRetriever -->|passes to| ContentCleaner
    ContentCleaner -->|cleans for| Recommender
    Recommender -->|indexes in| Elastic
    Recommender -->|queries| Elastic
    Recommender -->|stores metadata| RelationalDB

    NLPML -->|calls| NLPServers
    NLPML -->|uses| RelationalDB

    ExSessionMgmt -->|logs sessions in| RelationalDB
    ExSessionMgmt -->|invokes| BehaviorSched
    BehaviorSched -->|reads history from| RelationalDB

    Emailer -->|sends email via| SMTP

    YouTubeInt -->|calls| YouTubeAPI
    YouTubeInt -->|stores data in| RelationalDB

    %% Click Events
    click APIApp "https://github.com/gimchedli/zeeguu/blob/main/api/app.py"
    click APIApp "https://github.com/gimchedli/zeeguu/blob/main/api/cross_domain_app.py"
    click AccountsEP "https://github.com/gimchedli/zeeguu/blob/main/api/endpoints/accounts.py"
    click ExercisesEP "https://github.com/gimchedli/zeeguu/blob/main/api/endpoints/exercises.py"
    click ExerciseSessionsEP "https://github.com/gimchedli/zeeguu/blob/main/api/endpoints/exercise_sessions.py"
    click NotificationsEP "https://github.com/gimchedli/zeeguu/blob/main/api/endpoints/user_notifications.py"
    click UserVideoEP "https://github.com/gimchedli/zeeguu/blob/main/api/endpoints/user_video.py"
    click WatchingSessionEP "https://github.com/gimchedli/zeeguu/blob/main/api/endpoints/user_watching_session.py"

    click AccountMgmt "https://github.com/gimchedli/zeeguu/blob/main/core/account_management/user_account_creation.py"
    click AccountMgmt "https://github.com/gimchedli/zeeguu/blob/main/core/account_management/user_account_deletion.py"

    click ContentRetriever "https://github.com/gimchedli/zeeguu/blob/main/core/content_retriever/article_downloader.py"
    click ContentRetriever "https://github.com/gimchedli/zeeguu/blob/main/core/content_retriever/parse_with_newspaper.py"
    click ContentRetriever "https://github.com/gimchedli/zeeguu/blob/main/core/content_retriever/parse_with_readability_server.py"
    click ContentRetriever "https://github.com/gimchedli/zeeguu/blob/main/core/content_retriever/video_dowloader.py"
    click ContentRetriever "https://github.com/gimchedli/zeeguu/blob/main/core/feed_handler/feed_handler.py"
    click ContentRetriever "https://github.com/gimchedli/zeeguu/blob/main/core/feed_handler/rssfeed.py"
    click ContentRetriever "https://github.com/gimchedli/zeeguu/blob/main/core/feed_handler/newspaperfeed.py"

    click ContentCleaner "https://github.com/gimchedli/zeeguu/blob/main/core/content_cleaning/content_cleaner.py"
    click ContentCleaner "https://github.com/gimchedli/zeeguu/blob/main/core/content_cleaning/unicode_normalization.py"

    click Recommender "https://github.com/gimchedli/zeeguu/blob/main/core/content_recommender/elastic_recommender.py"
    click Recommender "https://github.com/gimchedli/zeeguu/blob/main/core/content_quality/quality_filter.py"

    click NLPML "https://github.com/gimchedli/zeeguu/blob/main/core/nlp_pipeline/spacy_wrapper.py"
    click NLPML "https://github.com/gimchedli/zeeguu/blob/main/core/nlp_pipeline/automatic_gec_tagging.py"
    click NLPML "https://github.com/gimchedli/zeeguu/blob/main/core/nlp_pipeline/alignment_errant.py"
    click NLPML "https://github.com/gimchedli/zeeguu/blob/main/core/nlp_pipeline/edit_errant.py"
    click NLPML "https://github.com/gimchedli/zeeguu/blob/main/core/nlp_pipeline/confusion_generator.py"
    click NLPML "https://github.com/gimchedli/zeeguu/blob/main/core/ml_models/paywall_detector.py"
    click NLPML "https://github.com/gimchedli/zeeguu/blob/main/core/ml_models/binary/tfidf_multi_paywall_detect.joblib"
    click NLPML "https://github.com/gimchedli/zeeguu/blob/main/core/tokenization/stanza_tokenizer.py"
    click NLPML "https://github.com/gimchedli/zeeguu/blob/main/core/tokenization/nltk_tokenizer.py"
    click NLPML "https://github.com/gimchedli/zeeguu/blob/main/core/tokenization/zeeguu_tokenizer.py"

    click ExSessionMgmt "https://github.com/gimchedli/zeeguu/blob/main/core/exercises/similar_words.py"
    click ExSessionMgmt "https://github.com/gimchedli/zeeguu/blob/main/core/model/user_exercise_session.py"
    click ExSessionMgmt "https://github.com/gimchedli/zeeguu/blob/main/core/sql/learner/exercises_history.py"

    click BehaviorSched "https://github.com/gimchedli/zeeguu/blob/main/core/behavioral_modeling/scroll_last_reading_percentage.py"
    click BehaviorSched "https://github.com/gimchedli/zeeguu/blob/main/core/word_scheduling/adaptive/scheduling_algo.py"
    click BehaviorSched "https://github.com/gimchedli/zeeguu/blob/main/core/word_scheduling/basicSR/basicSR.py"

    click Emailer "https://github.com/gimchedli/zeeguu/blob/main/core/emailer/zeeguu_mailer.py"
    click Emailer "https://github.com/gimchedli/zeeguu/blob/main/core/emailer/password_reset.py"
    click Emailer "https://github.com/gimchedli/zeeguu/blob/main/core/emailer/user_activity.py"

    click YouTubeInt "https://github.com/gimchedli/zeeguu/blob/main/core/youtube_api/youtube_api.py"

    click RelationalDB "https://github.com/gimchedli/zeeguu/tree/main/core/model/"
    click RelationalDB "https://github.com/gimchedli/zeeguu/blob/main/core/sql/queries/query_loader.py"
    click RelationalDB "https://github.com/gimchedli/zeeguu/blob/main/core/sql/queries/words_to_study.sql"
    click RelationalDB "https://github.com/gimchedli/zeeguu/blob/main/core/sql/learner/words.py"

    click Elastic "https://github.com/gimchedli/zeeguu/blob/main/core/elastic/indexing.py"
    click Elastic "https://github.com/gimchedli/zeeguu/blob/main/core/elastic/basic_ops.py"
    click Elastic "https://github.com/gimchedli/zeeguu/blob/main/core/elastic/elastic_query_builder.py"
    click Elastic "https://github.com/gimchedli/zeeguu/blob/main/core/semantic_search/elastic_semantic_search.py"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef service fill:#ade,stroke:#333,stroke-width:1px
    classDef datastore fill:#fea,stroke:#333,stroke-width:1px
    classDef external fill:#bfc,stroke:#333,stroke-width:1px
```
