# rodrichie/bee-productivity-analyzer architecture

> Architecture diagram of the GitHub repository rodrichie/bee-productivity-analyzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rodrichie/bee-productivity-analyzer
- Repository: https://github.com/rodrichie/bee-productivity-analyzer

## Overview

##### Project type and purpose
- This is a full-stack web application called “Bee Productivity Analyzer.”
- Front-end: React single-page application (SPA) that provides a chat UI, media upload, real-time camera integration, and data visualizations.
- Back-end: Python/Flask API server exposing REST endpoints and WebSocket events for real-time processing.
- Core functionality: AI-powered text and media analysis of beehive conditions, trend tracking, historical reporting, and real-time feedback.

##### File structure
- Top-level:
- Dockerfile, .dockerignore, .gitignore, .babelrc, package.json, requirements.txt
- README.md + API_DOCUMENTATION.md
- app/ (Flask application)
- app/controllers: API route handlers (analysis_controller.py)
- app/routes: route definitions (token_routes.py)
- app/handlers: domain-specific event handlers (media_events.py, socket_events.py, intergrated_handlers.py)
- app/services: business logic (data_integration_service.py)
- app/models: data and ML components (classifier, gemini_model, media_analyzer, trend_analyzer, reporting_system, knowledge_base, token, analysis_metrics)
- app/utils: cross-cutting concerns (auth, error_middleware, rate_limiter, session_manager, logging_config, feedback_system, progress_tracker, token_blacklist)
- app/static/js: React source code (App.jsx + component hierarchy)
- app/templates/index.html: single-page shell for React
- Other: package-lock.json, venv/

##### Extract architecture insights from the README
- REST endpoints for text queries, media uploads, token management
- Real-time WebSocket channels for immediate feedback
- React build step via Babel → dist/
- External dependency on “Gemini” AI API (requires GEMINI_API_KEY)
- Data visualization uses interactive charts (likely a JS charting library)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        direction TB
        Browser["Client Browser (React SPA)"]:::frontend
        subgraph "React Components"
            direction TB
            BeekeepingAnalyzer["BeekeepingAnalyzer Component"]:::frontend
            DataVisualizer["DataVisualizer Component"]:::frontend
            MediaAnalyzer["MediaAnalyzer Component"]:::frontend
        end
        StaticAssetServer["Static Asset Server\n(serves index.html & bundle.js)"]:::frontend
    end

    %% Server Side
    subgraph "Server Side"
        direction TB
        Main["Flask App Entry Point\n(main.py)"]:::backend

        subgraph "API Layer"
            direction TB
            AnalysisController["AnalysisController\n(/analysis, /media)"]:::backend
            TokenRoutes["TokenRoutes\n(/token)"]:::backend
        end

        subgraph "Event Handlers"
            direction TB
            SocketEvents["SocketEvents Handler"]:::backend
            MediaEvents["MediaEvents Handler"]:::backend
            IntegratedHandlers["IntegratedHandlers"]:::backend
        end

        subgraph "Service Layer"
            direction TB
            DataIntegrationService["DataIntegrationService"]:::service
        end

        subgraph "Model & ML Layer"
            direction TB
            Classifier["Classifier"]:::model
            GeminiModel["GeminiModel (AI API Wrapper)"]:::model
            MediaAnalyzerModel["MediaAnalyzer"]:::model
            TrendAnalyzer["TrendAnalyzer"]:::model
            ReportingSystem["ReportingSystem"]:::model
            AnalysisMetrics["AnalysisMetrics"]:::model
            KnowledgeBase["KnowledgeBase DB Model"]:::model
            TokenModel["Token Model"]:::model
        end

        subgraph "Utilities"
            direction TB
            Auth["Auth"]:::util
            ErrorMiddleware["ErrorMiddleware"]:::util
            RateLimiter["RateLimiter"]:::util
            SessionManager["SessionManager"]:::util
            TokenBlacklist["TokenBlacklist"]:::util
            LoggingConfig["LoggingConfig"]:::util
            FeedbackSystem["FeedbackSystem"]:::util
            ProgressTracker["ProgressTracker"]:::util
        end

        subgraph "Storage & DB"
            direction TB
            DB["PostgreSQL / KnowledgeBase DB"]:::storage
            MediaStorage["Media Storage"]:::storage
        end

        subgraph "External Services"
            direction TB
            GeminiAPI["Gemini AI API"]:::external
        end
    end

    %% Connections
    Browser -->|loads bundle via HTTP| StaticAssetServer
    StaticAssetServer -->|serves App.jsx bundle| Browser

    Browser -->|HTTP POST/GET JSON| AnalysisController
    Browser -->|HTTP POST multipart| AnalysisController
    Browser -->|HTTP POST/GET JSON| TokenRoutes
    Browser <-->|WebSocket JSON| SocketEvents

    AnalysisController -->|calls| DataIntegrationService
    TokenRoutes -->|uses| TokenModel
    TokenRoutes -->|checks| TokenBlacklist
    AnalysisController -->|stores files| MediaStorage
    AnalysisController -->|queries| DB

    SocketEvents -->|dispatches events to| IntegratedHandlers
    MediaEvents -->|handles media events| DataIntegrationService
    IntegratedHandlers -->|orchestrates| DataIntegrationService

    DataIntegrationService -->|invokes| Classifier
    DataIntegrationService -->|invokes| GeminiModel
    DataIntegrationService -->|invokes| MediaAnalyzerModel
    DataIntegrationService -->|invokes| TrendAnalyzer
    DataIntegrationService -->|invokes| ReportingSystem
    DataIntegrationService -->|records metrics in| AnalysisMetrics
    DataIntegrationService -->|reads/writes| KnowledgeBase

    DataIntegrationService -->|logs via| LoggingConfig
    DataIntegrationService -->|auth via| Auth
    DataIntegrationService -->|rate limits via| RateLimiter
    DataIntegrationService -->|tracks progress via| ProgressTracker
    DataIntegrationService -->|feedback via| FeedbackSystem
    AnalysisController -->|error handling| ErrorMiddleware
    TokenRoutes -->|session mgmt| SessionManager

    TrendAnalyzer -->|reads data from| DB
    ReportingSystem -->|reads data from| DB

    GeminiModel -->|HTTP REST| GeminiAPI

    %% Click Events
    click Browser "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/static/js/App.jsx"
    click BeekeepingAnalyzer "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/static/js/components/BeekeepingAnalyzer.jsx"
    click DataVisualizer "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/static/js/components/DataVisualizer.jsx"
    click MediaAnalyzer "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/static/js/components/MediaAnalyzer.jsx"
    click StaticAssetServer "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/templates/index.html"
    click StaticAssetServer "https://github.com/rodrichie/bee-productivity-analyzer/tree/main/app/static/js"
    click Main "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/main.py"
    click AnalysisController "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/controllers/analysis_controller.py"
    click TokenRoutes "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/routes/token_routes.py"
    click SocketEvents "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/handlers/socket_events.py"
    click MediaEvents "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/handlers/media_events.py"
    click IntegratedHandlers "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/handlers/intergrated_handlers.py"
    click DataIntegrationService "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/services/data_intergration_service.py"
    click Classifier "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/models/classifier.py"
    click GeminiModel "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/models/gemini_model.py"
    click MediaAnalyzerModel "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/models/media_analyzer.py"
    click TrendAnalyzer "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/models/trend_analyzer.py"
    click ReportingSystem "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/models/reporting_system.py"
    click AnalysisMetrics "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/models/analysis_metrics.py"
    click KnowledgeBase "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/models/knowledge_base.py"
    click TokenModel "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/models/token.py"
    click Auth "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/utils/auth.py"
    click ErrorMiddleware "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/utils/error_middleware.py"
    click RateLimiter "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/utils/rate_limiter.py"
    click SessionManager "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/utils/session_manager.py"
    click TokenBlacklist "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/utils/token_blacklist.py"
    click LoggingConfig "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/utils/logging_config.py"
    click FeedbackSystem "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/utils/feedback_system.py"
    click ProgressTracker "https://github.com/rodrichie/bee-productivity-analyzer/blob/main/app/utils/progress_tracker.py"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#004d40;
    classDef backend fill:#ffebee,stroke:#b71c1c,color:#880e4f;
    classDef service fill:#e8f5e9,stroke:#1b5e20,color:#2e7d32;
    classDef model fill:#e3f2fd,stroke:#0d47a1,color:#1565c0;
    classDef util fill:#fff3e0,stroke:#e65100,color:#bf360c;
    classDef storage fill:#f3e5f5,stroke:#4a148c,color:#6a1b9a;
    classDef external fill:#f0f4c3,stroke:#827717,color:#afb42b
```
