# mixbits/giteamgmt architecture

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

- Interactive diagram: https://gitdiagram.com/mixbits/giteamgmt
- Repository: https://github.com/mixbits/giteamgmt

## Overview

##### Project Type and Purpose
- This is a cross-platform, desktop GUI application written in Python (3.8+) using Tkinter.
- Its purpose is to simplify and automate pushing local directories to Gitea repositories via two modes: Git CLI push and direct Gitea API file upload.
- It also provides repository and branch management (e.g., emptying branches) through a “Management” tab.

##### File Structure Analysis
- Top-level files:
- app.py            – Main Python application entry point (UI + logic)
- requirements.txt  – Python dependencies (e.g., requests)
- config.ini        – Stores non-sensitive preferences (Gitea URL, username)
- run.sh / run.bat  – Shell and batch scripts to bootstrap venv, install deps, launch app
- LICENSE, README.md
- Directories:
- debug/troubleshooting.md  – Troubleshooting guide
- logs/                     – Changelog and runtime logs
- images/ and screenshots/  – GUI assets and documentation images
- Patterns:
- MVC-style separation:
– View: Tkinter GUI components
– Controller/Service: app.py logic orchestrating user actions
– Model/Persistence: config.ini, logs

##### Architectural Insights from README
- Two upload modes (Git CLI vs. Gitea API) imply branching logic in the service layer.
- Real-time progress monitoring: event callbacks from service layer to UI.
- Use of external dependencies: Git must be on PATH for push mode; direct HTTP calls to Gitea API.
- Wrapper scripts handle environment setup and error-recovery for missing tkinter.

##### Main Components and Their Interactions
- Frontend (UI Layer)
– Tkinter windows, dialogs, tabbed interface (Upload, Management, Help)
– Drag-and-drop support, file/folder selection
– Progress bars and status messages

- Backend (Service Layer)
– GitService: wraps Git CLI calls (init, commit, push, fetch, merge)
– ApiService: handles HTTP requests to Gitea REST API (repository creation, file uploads, search, branch operations)
– ConfigService: reads/writes config.ini
– LoggingService: writes to logs/*.log and exposes logs to UI

- Integration Layer
– External Git CLI (shell out)
– Gitea Server (HTTPS API)

- Data Layer
– Local file system (project folders, optional ZIP extraction)
– config.ini for preferences
– logs directory for detailed operation history

##### Architectural Patterns and Principles
- MVC-like structure separating UI from business logic.
- Single-responsibility services for Git vs. API operations.
- One-shot authentication URLs ensure credentials are not persisted.
- Wrapper scripts implement a self-healing bootstrap process (v-env recreation, tkinter tests).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        UI["UI Layer\n(Tkinter UI)"]:::ui
    end

    %% Service Layer
    subgraph "Service Layer"
        GitService["GitService\n(wraps Git CLI)"]:::core
        ApiService["ApiService\n(Gitea REST API)"]:::core
        ConfigService["ConfigService\n(read/write prefs)"]:::core
        LoggingService["LoggingService\n(log management)"]:::core
    end

    %% Data & Config Layer
    subgraph "Data & Config"
        ConfigData((config.ini)):::data
        Logs((logs/)):::data
    end

    %% External Systems
    subgraph "External Systems"
        GitCLI["Git CLI\n(subprocess)"]:::external
        GiteaAPI["Gitea Server\n(HTTPS REST API)"]:::external
    end

    %% Helper Scripts & Docs
    subgraph "Repository Artifacts"
        RunShell["run.sh"]:::doc
        RunBatch["run.bat"]:::doc
        Troubleshoot["troubleshooting.md"]:::doc
        Images["images/"]:::doc
        Screenshots["screenshots/"]:::doc
        Requirements["requirements.txt"]:::doc
        Readme["README.md"]:::doc
        License["LICENSE"]:::doc
    end

    %% Connections
    UI -->|"invoke upload/management"| GitService
    UI -->|"invoke upload/management"| ApiService
    GitService -->|"git init/commit/push"| GitCLI
    ApiService -->|"POST/PUT requests"| GiteaAPI
    ConfigService -->|"read/write prefs"| ConfigData
    LoggingService -->|"write logs"| Logs
    GitService -->|"config access"| ConfigService
    ApiService -->|"config access"| ConfigService
    GitService -->|"log events"| LoggingService
    ApiService -->|"log events"| LoggingService
    GitService -->|"progress/event callback"| UI
    ApiService -->|"progress/event callback"| UI

    %% Click Events
    click UI "https://github.com/mixbits/giteamgmt/blob/main/app.py"
    click GitService "https://github.com/mixbits/giteamgmt/blob/main/app.py"
    click ApiService "https://github.com/mixbits/giteamgmt/blob/main/app.py"
    click ConfigService "https://github.com/mixbits/giteamgmt/blob/main/config.ini"
    click LoggingService "https://github.com/mixbits/giteamgmt/tree/main/logs/"
    click RunShell "https://github.com/mixbits/giteamgmt/blob/main/run.sh"
    click RunBatch "https://github.com/mixbits/giteamgmt/blob/main/run.bat"
    click Troubleshoot "https://github.com/mixbits/giteamgmt/blob/main/debug/troubleshooting.md"
    click Images "https://github.com/mixbits/giteamgmt/tree/main/images/"
    click Screenshots "https://github.com/mixbits/giteamgmt/tree/main/screenshots/"
    click Requirements "https://github.com/mixbits/giteamgmt/blob/main/requirements.txt"
    click Readme "https://github.com/mixbits/giteamgmt/blob/main/README.md"
    click License "https://github.com/mixbits/giteamgmt/tree/main/LICENSE"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#98FB98,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef data fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef doc fill:#FFE4B5,stroke:#333,stroke-width:1px
```
