Loading Modoroco
THE-1807

Pre-release / Foundation verified

Modoroco

One timer domain. Native desktop focus, reusable routines, persistent sessions, real-time events, and a versioned API.

Inspect architectureView repository
  1. Created
  2. Started
  3. Paused ⇆ resumed
  4. Phase complete
  5. Cancelled / completed

01 / One domain

Focus is the interface. Timing is the infrastructure.

The desktop application is one interface over a shared timer domain. Sessions derive their visible countdown from authoritative UTC timestamps rather than a database write every second.

That state model supports recovery across process, network, API, worker, and container interruption. Server-Sent Events are reserved for the transitions shown here — not a per-second tick.

02 / Architecture

Built as a system, not a countdown widget.

Domain logic remains independent from FastAPI, SQLAlchemy, PostgreSQL, Docker, HTTP, environment configuration, and the Qt desktop interface.

InterfacesNative PySide6 desktop, versioned FastAPI REST interface, OpenAPI 3.1, Server-Sent Events
CorrectnessExplicit state transitions, idempotency, optimistic concurrency, tenant isolation, timestamp-authoritative timing
RuntimePostgreSQL persistence, Alembic migrations, worker-driven transitions, transactional outbox
VerificationHosted PostgreSQL and Docker system testing, concurrent worker claims, restart recovery, named-volume persistence
OperationsNon-root image, health/readiness endpoints, structured logging, Prometheus-compatible metrics, SBOM and provenance workflows
Runtime
Python 3.13
Contract
OpenAPI 3.1 · REST + SSE
Persistence
PostgreSQL 18 verified
Image
184 MB optimized server

03 / Meaningful events

No server event every second.

Clients render the countdown locally. SSE is reserved for changes that matter: session creation, start, pause, resume, phase completion, cancellation, and completion.

Current state

Verified foundation, active hardening.

The timer domain, desktop, API, persistence, worker, outbox, concurrency controls, containers, and hosted verification exist. Security hardening, deeper observability, release packaging, and deployment preparation remain active work.

Modoroco is not represented as production-ready.