Architecture

Architecture: One Engine, Every Trigger

The core idea of URGithub is that different triggers converge into one engine. A trigger only decides when an operation starts — it never creates a second implementation of the Git synchronization logic.

Single runner, single pipeline

All triggers — startup, scheduled, file change, manual, shutdown — call the same entry point (runner.run_trigger()), which executes the identical gate chain and pipeline. There is never an unsafer path.

flowchart TD
    S[Startup] --> R["SINGLE RUNNER - runner.run_trigger()"]
    C[Scheduled] --> R
    F[File change] --> R
    M[Manual] --> R
    D[Shutdown quick-push] --> R
    R --> A[DISCOVER]
    A --> B[SCAN]
    B --> V[VALIDATE]
    V --> Y[SYNC]
    Y --> K[COMMIT]
    K --> P[PUSH]
    P --> J[VERIFY]
    J --> L[JOURNAL]
    L --> H[report.html]

Loading

The advantage of this architecture is consistency: a trigger selects when the operation starts, not how the repositories are processed.

What a normal run does

flowchart LR
    G[registration gate] --> L[lock] --> J1[journal run-start] --> E[light env check]
    E --> P1[DISCOVER] --> P2[SCAN] --> P3[VALIDATE] --> P4[SYNC] --> P5[COMMIT/PUSH]
    P5 --> P6[JOURNAL] --> P7[REPORT] --> SH[SHOW]
    SH --> J2[journal run-end] --> UL[release lock]

Loading

The SHOW rule decides how the report is presented:

Context	Behavior
Interactive run	Opens the report in the browser
Background / scheduled run	Shows a toast (Windows)
Shutdown quick-push	Never opens the report

The global lock serializes runs — two runs can never fire at once. A stale lock is cleared after 15 seconds.

Safety boundary

URGithub strictly separates a trigger from a repository operation:

flowchart TB
    TR["Trigger - 'Start a run'"] --> DS[Discover]
    DS --> SC[Scan]
    SC --> SEC[Security checks]
    SEC --> SV[Repository-state validation]
    SV --> DA[Determine safe action]
    DA --> SN[Sync]
    SN --> CM[Commit]
    CM --> PS[Push]
    PS --> VF[Verify]
    VF --> RP[Report]

Loading

A trigger means "Start a run." It does not mean "Immediately push everything." Every run must pass through the safety pipeline. This distinction is central to the design.

Safe or blocked

flowchart LR
    Q{Inspection} -->|SAFE| C[CONTINUE]
    Q -->|UNSAFE| B[BLOCK]
    B --> R[REPORT]

Loading

A blocked repository should never silently become a destructive operation.

Setup philosophy

URGithub deliberately separates installation, registration, scanning, validation, and synchronization — so a newly installed tool never immediately makes uncontrolled repository changes.

flowchart LR
    I[INSTALL] --> K[CHECK] --> R[REGISTER] --> SN[SCAN] --> V[VERIFY] --> SY[SYNC] --> A[AUTOMATE]

Loading

The safest first interaction with a new machine follows this path, ending only when the manual workflow has been proven.

Project layout

<project folder>\
├── urgithub.py            ← entry point (thin: cli.main)
├── urgithub_core\
│   ├── cli.py             ← argument handling + config/schedule/watch/tray/status commands
│   ├── runner.py          ← universal run_trigger() pipeline + gates
│   ├── discovery.py       ← registry, reconciliation, adoption, clone, quarantine, rename
│   ├── scan.py            ← 23-point inspection + validation gates
│   ├── sync.py            ← safe pull/commit/push + shutdown quick-push
│   ├── report.py          ← report.html (dark theme) + archiving + show rules + toasts
│   ├── scheduler.py       ← Task Scheduler integration + launcher deploy + next-run math
│   ├── watch.py           ← debounced file watcher
│   ├── tray.py            ← control panel GUI
│   ├── gui.py             ← Control Center (Dashboard / Repos / Schedule / Settings / Logs / Help)
│   ├── wizard.py          ← registration wizard (GUI + console fallback)
│   ├── envcheck.py        ← registration environment checks
│   ├── config.py          ← defaults, deep-merge, locator, load/save
│   ├── paths.py           ← path derivation + ensure_all
│   ├── registry.py        ← JSON repo registry
│   ├── journal.py         ← append-only JSONL journal
│   ├── lock.py            ← PID-based run lock
│   ├── logs.py            ← rotating logging
│   ├── prompt.py          ← unified GUI/terminal confirmation funnel
│   └── gitops.py          ← non-interactive git/gh wrappers
├── Run\                   ← dev launchers (start/scan/sync/shutdown/schedule/manual.bat)
├── docs\                  ← guides + roadmap + spec/00..05
└── .gitignore

No third-party dependencies. No build step. python urgithub.py is all there is.

Deployed (runtime) layout

The base location is where URGithub keeps its runtime data — separate from the source-code directory, so updating the app never mixes with managed repositories.

<base location>\urgithub\
├── logs\                 ← application.log + error.log (rotating)
├── repos in github\      ← ACTIVE managed repositories
├── deleted repos\        ← quarantined archives (never auto-deleted)
├── Run\                  ← deployed .bat launchers + NOTES.md
└── .urgithub\            ← hidden data
    ├── config.json       ← all settings
    ├── shutdown-task.xml ← generated Task Scheduler XML
    ├── database\
    │   ├── registry.json ← repo registry (status, SHAs, quarantine state)
    │   └── journal.jsonl ← append-only event journal
    ├── reports\          ← report.html + archive\
    ├── locks\            ← run.lock (stale after 15 s)
    └── cache\ credentials\

The base location is not the same thing as the URGithub source-code directory. The source repository contains the application; the base location contains runtime data and managed repository state.

Performance

Measured on a real 12-repository account (one repo with 3,608 tracked files):

• Full manual scan of all 12 repos: ~42 seconds.
• Per-file last-commit history is a single git log walk per repo — not one process per file.
• Idempotent: a second run with nothing to do clones nothing and pushes nothing.

What URGithub should never be expected to do

URGithub is an automation and safety layer around Git operations. It is not a replacement for:

• Git
• GitHub
• GitHub authentication
• repository backups
• source-control understanding
• code review
• release management

Automatic synchronization does not eliminate the need for good repository practices — important repositories should still have appropriate backups and recovery procedures.

See Repositories & Sync for how discovery, reconciliation, and synchronization actually behave.