1. The Core Bottleneck: What Engineering Flaw Does It Shatter?

The prevailing commercial model for fitness tracking software binds user telemetry and structural workout history directly to closed-source cloud infrastructure. Workout metrics, custom 1RM progression models, and multple years of set logs are forcefully stored on third-party servers. If the service provider adjusts pricing policies, suffers an infrastructure outage, or shuts down operations entirely, historical curves vanish instantly. Furthermore, these applications routinely execute intrusive telemetry scripts, transmitting biological metrics and training preferences to remote data warehouses without explicit consent.

onsense. openGym counters this dynamic by stripping away cloud dependencies entirely. Its architecture centers around self-contained local containers, persisting data directly within user-controlled host directories. Users no longer pay recurring monthly subscription fees to commercial entities, nor do they risk exposing workout habits to advertising algorithms. It bridges modern web application experiences—such as Progressive Web Apps, hardware-backed Passkey biometric authentication, and offline read-write capabilities—with the absolute control of traditional self-hosted software.

💡 Core Architectural Insight: By binding modern frontend state management directly to local persistent volumes, openGym eliminates deployment friction while completely removing third-party servers as single points of failure.

2. Core Architecture and Underlying Data Flow

The backend separates lightweight API services from static web frontends, encapsulating both within Docker containers. When clients initiate exercise queries, set logs, or routine synchronizations, requests route through the internal reverse proxy to the local persistent storage layer. The built-in synchronization engine handles concurrent multi-device modifications, resolving conflicts through deterministic merge algorithms rather than blindly overwriting recent writes.

[ Mobile / Web Client ] ---> [ Nginx Proxy / Gateway ] ---> [ API Service Container ]
                                                                   │
                                                                   ▼
[ Local Persistent Volume ] <--- [ Sync & Merge Engine ] <--- [ SQLite / File Store ]

During initialization, exercise media assets (~140MB of GIFs and animations) are fetched on first boot, after which all interactions execute locally within the LAN or a secured private server. Geolocation and device fingerprints are stripped client-side prior to upload. The optional AI coach module is decoupled from the core image; users supply custom API keys for Anthropic, OpenAI, Gemini, or any OpenAI-compatible endpoint like Ollama, keeping the execution path entirely transparent.

3. Technology Selection and Hardcore Performance Benchmark

Evaluation Dimension This Solution (openGym) Traditional Paradigm (Strong / Hevy) Typical Open-Source Gym Apps Production Environment Yield
Data Storage Location Local Docker Volume / Custom Path Commercial Cloud Database (AWS/GCP) Unstructured Local JSON Files 100% Data Sovereignty, immune to cloud outages
Authentication & Security Hardware Passkey (Face ID/Touch ID) Email/Password + Third-Party OAuth Plaintext Passwords or Basic Auth Eliminates credential stuffing and central leaks
Operational Overhead Single docker compose up, RAM < 150MB Ongoing monthly subscription ($5-$10/mo) Complex Node/Python source compilation Zero subscription cost, minimal resource footprint
Multi-Device Sync Real-time conflict-merging sync engine Centralized cloud locking mechanism None or manual import/export only Parallel multi-device editing without loss
Offline Capability Full PWA offline read/write cache Degraded functionality on weak networks Basic offline viewing only Full operational readiness in dead zones

The architectural selection directly addresses core developer demands: no middlemen, no sudden subscription price hikes, and absolute physical ownership of data paths.

4. Hands-on Geek Practice: Zero to Minimal Production Loop

On any server or workstation running Docker with Docker Compose support, execute the following initialization script to fetch and launch the containerized stack.

# Clone the official repository to the local workspace
git clone https://github.com/DuarteSantos8/openGym
cd openGym

# Duplicate the environment variable template
cp .env.example .env

# Pre-pull prebuilt multi-architecture images (amd64 and arm64)
docker compose pull

# Launch the containerized service cluster in detached mode
docker compose up -d

Once services initialize successfully, open http://localhost:8080 in a browser. Tap Create profile to complete local initialization. The initial boot automatically provisions and unpacks static media assets (~140MB exercise demonstration library).

5. Production Gotchas and Deployment Warnings

Deploying openGym to public production servers or maintaining long-term usage requires awareness of network topology and hardware binding constraints.

⚠️ Gotcha Warning: Passkey Binding Failure: If RP_ID and ORIGIN within .env are not configured to point to a valid HTTPS domain, mobile browsers will reject hardware Passkey registration and assertion. Always pair the stack with Caddy, Traefik, or Cloudflare Tunnel for valid TLS.

⚠️ Gotcha Warning: Initial Startup Network Timeout: During the initial docker compose up -d execution, the API container provisions 140MB of exercise assets. Poor direct connectivity to container registries may trigger health check timeouts; ensure appropriate proxy routing if deploying behind restrictive firewalls.

⚠️ Gotcha Warning: Routine State Backups: Because data ownership rests entirely with the operator, the host-mounted volume serves as the single source of truth. Implement automated cron jobs to regularly archive and encrypt persistent volumes off-site to mitigate physical disk failures.