How zeeguu/api works
1. System shape
This repo is a Python backend monorepo centered on the Zeeguu API, with two auxiliary NLP services (asr_service, stanza_service) and a large set of maintenance/ETL scripts under tools/ and zeeguu/operations/. The main runtime is the API service; the other parts support content ingestion, model updates, and offline batch work.
2. API boundary
The entry point for the product backend is zeeguu/api/app.py, with route modules under zeeguu/api/endpoints/. These endpoints are organized by domain: accounts, articles, bookmarks/words, sessions, exercises, search, translation, notifications, stats, topics, video/audio, and a dedicated teacher_dashboard/ subtree. zeeguu/api/utils/ contains cross-cutting concerns such as session handling, rate limiting, security checks, background jobs, and JSON/abort wrappers.
3. Core domain layer
Most business logic lives in zeeguu/core/. This layer is split by capability rather than by transport: account management, content retrieval and cleaning, bookmark operations, exercises, scheduling, user statistics, friendships, leaderboards, badges, language difficulty, NLP, LLM services, translation services, audio lessons, verbal flashcards, and content recommender logic. The API layer should be treated as thin orchestration over this core layer.
4. Persistence model
The persistence boundary is represented by zeeguu/core/model/, which contains the domain entities for users, articles, bookmarks, meanings, sessions, topics, feeds, videos, audio lessons, badges, notifications, cohorts, and many join/association tables. Database evolution is managed via the many SQL migration files in tools/migrations/, which indicates a schema-driven MySQL-backed architecture with frequent evolutionary changes.
5. Reading/content ingestion pipeline
Content enters the system through feed and crawler components in zeeguu/core/feed_handler/, zeeguu/core/content_retriever/, and the crawler scripts under tools/crawler/ and zeeguu/operations/crawler/. Raw articles/videos are downloaded, parsed, cleaned, quality-filtered, and then stored as content entities. The pipeline also includes content quality detection (advertorials, disturbing content, paywalls) and tokenization/normalization before the material is used in user-facing flows.
6. Search and recommendation
Search and recommendation are backed by Elastic-related modules in zeeguu/core/elastic/, zeeguu/core/content_recommender/, and zeeguu/core/semantic_search/. These components build/query indexes, support semantic retrieval, and drive the “recommend texts in the zone of proximal development” use case described in the README. There is a clear flow from ingested content into search/indexing, then into personalized recommendations.
7. NLP and language understanding
Language processing is a major subsystem: tokenization (zeeguu/core/tokenization/), multi-word expression detection (zeeguu/core/mwe/), linguistic pipelines (zeeguu/core/nlp_pipeline/), translation services, and language difficulty estimation (zeeguu/core/language/). The code supports multiple strategies for difficulty assessment, including frequency-based, Flesch-Kincaid, and ML-based CEFR classification. This layer feeds both content annotation and learner modeling.
8. External AI/NLP services
Several modules are explicit adapters to external services: zeeguu/core/llm_services/ wraps providers such as Anthropic and DeepSeek for simplification, example generation, grammar correction, and validation; zeeguu/core/translation_services/ includes Deepl and Azure alignment; zeeguu/core/audio_lessons/azure_voice_synthesizer.py drives TTS. These integrations materially shape the architecture because lesson generation and text simplification depend on third-party AI services.
9. Audio lesson pipeline
Audio lessons are a distinct product subsystem. zeeguu/core/audio_lessons/ contains lesson generation, script building, suggestion validation, word selection, voice config, and ASR client integration. The standalone asr_service/ and stanza_service/ directories are deployed as separate containers, suggesting they are called over HTTP by the core service for speech recognition and NLP model execution.
10. Learner model and activity tracking
The app tracks reading, browsing, listening, watching, exercise sessions, bookmarks, and user word interactions through dedicated session and statistics modules. zeeguu/core/user_activity_hooks/, zeeguu/core/user_statistics/, zeeguu/core/reading_analysis/, and models like user_reading_session, user_browsing_session, user_listening_session, and user_word_interaction_history indicate a feedback loop where learner behavior updates the personalization model, streaks, badges, and study recommendations.
11. Teacher and cohort features
Teacher-facing functionality is first-class, not an add-on. zeeguu/api/endpoints/teacher_dashboard/ and core models such as teacher, cohort, teacher_cohort_map, and cohort_article_map support cohort management, student overviews, article management, and student exercise/reading views. This boundary is distinct from the learner-facing API and includes permission checks plus teacher-only decorators.
12. Notifications, onboarding, and social loop
User engagement features are implemented as separate subsystems: badges, daily streaks, onboarding messages, notifications, friendships, and leaderboards. These are mostly event-driven at the domain level through listeners/hooks, with persistence in dedicated tables. They reinforce the learning loop rather than serving as core content infrastructure.
13. Batch operations and maintenance
The repo contains a large operational surface in tools/ and zeeguu/operations/: data cleanup, backfills, migrations, reindexing, report generation, ML training, crawler jobs, and one-off fixes. This indicates the system relies heavily on offline maintenance scripts to keep the content corpus, learner model, and indexes consistent over time.
14. Deployment and environment
The project is containerized (Dockerfile, docker-compose.yml, service-specific Dockerfiles, gunicorn configs) and has CI workflows for tests, Docker image publishing, and architectural diff rendering. The README shows a local setup that depends on MySQL, optional Stanza models, and environment-based configuration, so runtime boundaries are container + DB + external NLP/AI services rather than a single monolith process.
Main entry points: endpoints/__init__.py Endpoints · model/__init__.py Domain models · article_downloader.py Ingest · llm_service.py Language AI
Components 19
API layer
HTTP app, routes, and cross-cutting request helpers
- API app · Main Zeeguu backend application bootstrap and wiring
zeeguu/api/app.py - Endpoints · Product API routes organized by domain
zeeguu/api/endpoints/__init__.py - Teacher API · Teacher-only dashboard routes and permissions
zeeguu/api/endpoints/teacher_dashboard/__init__.py - API utils · Session, security, rate limiting, background jobs, and response wrappers
zeeguu/api/utils/__init__.py
Core domain
Business logic, content processing, learner model, and persistence models
- Accounts · User creation, deletion, and account lifecycle
zeeguu/core/account_management/user_account_creation.py - Ingest · Fetches articles and videos from feeds and crawlers
zeeguu/core/content_retriever/article_downloader.py - Clean content · Normalizes text and filters low-quality or disturbing content
zeeguu/core/content_cleaning/content_cleaner.py - Search & recs · Indexing, search, semantic retrieval, and personalized recommendations
zeeguu/core/content_recommender/elastic_recommender.py - NLP · Tokenization, MWE detection, and linguistic pipeline support
zeeguu/core/tokenization/zeeguu_tokenizer.py - Language AI · LLM simplification, validation, translation, and difficulty estimation
zeeguu/core/llm_services/llm_service.py - Audio lessons · Lesson generation, TTS/ASR integration, and word selection
zeeguu/core/audio_lessons/daily_lesson_generator.py - Learner model · Reading, browsing, listening, exercise tracking, streaks, and progress
zeeguu/core/user_statistics/activity.py - Domain models · Core entities for users, content, sessions, topics, and learning state
zeeguu/core/model/__init__.py - Engagement · Badges, friendships, leaderboards, onboarding, and notifications
zeeguu/core/friends/friend_streak.py
Auxiliary services
Separate runtime services for ASR and NLP model execution
- ASR service · Standalone speech recognition runtime
asr_service/app.py - Stanza service · Standalone NLP model runtime for tokenization and linguistic tasks
stanza_service/app.py
Operations
Batch jobs, crawlers, migrations, and offline ML tasks
- Crawlers · Offline crawling and feed retrieval jobs
zeeguu/operations/crawler/crawl.py - Migrations · SQL-driven database evolution and backfills
tools/migrations/README.md - ML trainers · Batch training for CEFR and related classifiers
tools/ml/cefr_trainers/train_cefr_classifiers.py
Connections 24
- API app → Endpoints: registers · Main app wires all API routes
- API app → API utils: uses · Shared request and response helpers
- Endpoints → Accounts: orchestrates · Account endpoints delegate to core account logic
- Endpoints → Ingest: orchestrates · Content and upload endpoints reach into ingestion
- Endpoints → Search & recs: orchestrates · Search endpoints query retrieval and recommendation
- Endpoints → Learner model: orchestrates · Sessions, stats, and activity endpoints update learner state
- Endpoints → Teacher API: mounts · Teacher dashboard is a distinct API subtree
- Teacher API → Domain models: reads/writes · Teacher and cohort views depend on core entities
- Ingest → Clean content: feeds · Raw content is cleaned before use
- Clean content → Domain models: stores · Cleaned articles and related entities are persisted
- Ingest → Domain models: stores · Downloaded content becomes domain records
- Ingest → Search & recs: indexes · Ingested content is indexed for retrieval
- Search & recs → Domain models: queries · Search and recommendation read content and learner data
- NLP → Language AI: enriches · Language processing supports translation and difficulty work
- Language AI → Domain models: annotates · AI results are stored as meanings, examples, and assessments
- Audio lessons → Language AI: depends on · Lesson generation uses LLM and translation services
- Audio lessons → ASR service: calls · ASR is provided by a separate service
- Audio lessons → Stanza service: calls · Stanza-backed NLP is externalized into a service
- Learner model → Domain models: reads/writes · Activity tracking is persisted across session and history tables
- Learner model → Engagement: drives · Behavior updates badges, streaks, friends, and notifications
- Crawlers → Ingest: feeds · Offline crawlers populate the ingestion pipeline
- Migrations → Domain models: evolves · Schema changes and backfills shape the model layer
- ML trainers → Language AI: trains · Offline ML jobs improve difficulty and classification models
- NLP → Stanza service: depends on · Some NLP features use the external stanza runtime