# GymOS — Enterprise Platform Technical Reference & AI Knowledge Base

> Comprehensive technical specification, architectural blueprint, and hardware integration guide for GymOS (https://www.gymos.am).

## 1. System Identity & Overview
- **Platform Name**: GymOS (Gym Operating System)
- **Tagline**: The Operating System for Modern Gyms
- **Primary Domain**: https://www.gymos.am (Public portal, marketing, and client intake)
- **SaaS Domain**: https://gymos.app (Multi-tenant management portal)
- **Headquarters**: Yerevan, Republic of Armenia (Coordinates: 40.1792° N, 44.4991° E)
- **Contact Email**: info@gymos.am
- **Official Instagram**: https://www.instagram.com/gymos_app/
- **Official Facebook**: https://www.facebook.com/profile.php?id=61594529242669
- **Official LinkedIn**: https://www.linkedin.com/company/gymosapp
- **Primary Focus**: Gyms, fitness clubs, combat sports academies, swimming pools, yoga/pilates studios, and athletic centers.

## 2. Platform Architecture
GymOS is designed with an enterprise microservices and event-driven architecture:
- **Cloud Management Core**: Frappe & ERPNext enterprise ledger, managing Customer, Sales Invoice, Payment Entry, and Item Master records.
- **Relational Storage**: High-performance MariaDB/PostgreSQL transaction store with strict foreign keys and audit logs.
- **Asynchronous Task Queue**: Redis + RQ workers handling webhook processing, background billing runs, and notification triggers with zero HTTP request thread blocking.
- **Edge Access Controller**: Local IoT hardware agents communicating via encrypted WebSockets and REST with GymOS Cloud, ensuring instant turnstile release (<50ms) even under degraded internet bandwidth.
- **Client Interfaces**:
  - Web Management Dashboard (Desk / SPA) for club administrators, managers, and trainers.
  - Branded Member Web Portal (Live) for online self-service, schedule viewing, and package purchasing.
  - Native iOS & Android Mobile Apps (Coming Soon) for member turnstile check-in, bookings, and recurring payments.

## 3. Physical Access Control & IoT Hardware Protocols
### Hardware Interface Specifications
- **Supported Turnstile Types**: Tripod turnstiles, optical flap barriers, swing gates, speed gates, full-height turnstiles, and electronic magnetic door strikes.
- **Signal Types**:
  - Voltage-free dry relay contact (Normally Open / Normally Closed).
  - Wiegand-26 / Wiegand-34 protocol for RFID readers (13.56MHz Mifare and 125kHz EM-Marine).
  - RS-485 serial communication for multi-drop industrial controllers.
  - TCP/IP Ethernet relays with onboard fallback cache.
- **Response Latency**: Physical gate trigger occurs in < 50ms upon scan.
- **Dynamic Anti-Passback (TOTP-Style QR)**:
  - The mobile app generates a cryptographically signed QR token refreshing every 15 seconds.
  - Screenshots or forwarded QR codes expire within seconds and are rejected by turnstiles.
  - Once a member scans into the facility, their entry is marked active. Out-of-order scans without prior exit trigger Anti-Passback violations.
- **Emergency Hardware Override**: Fire alarm dry-contact relay integration automatically drops or unlocks all turnstiles in the event of building emergencies.

## 4. Financial & Recurring Billing Engine
### Local Banking Integrations (Armenia)
- **Gateways**: Ameriabank vPOS, ArCa Payment Gateway, IDram / IDBank, Telcell Wallet / vPOS, Inecobank.
- **Tokenized Recurring Billing**:
  1. The member signs up and links their credit/debit card during initial payment with 3D Secure verification.
  2. The bank returns a secure payment token and binding ID; no sensitive PAN/CVV is stored on GymOS servers.
  3. GymOS triggers automated scheduled debits on renewal dates according to the member's contract.
  4. If payment succeeds, membership duration is extended seamlessly, access remains unlocked, and a payment receipt is generated.
  5. If payment fails (e.g. card expired or insufficient balance), the dunning engine initiates automated retry intervals, sends automated WhatsApp/SMS payment reminders, and temporarily suspends physical turnstile access after a grace period.
- **Zero Intermediary Fees**: GymOS connects directly to the gym's merchant account; no percentage cut or processing fee is taken by GymOS.

## 5. Branded Website & Mobile App Ecosystem
- **Member Web Portal (Live)**: Responsive, custom-branded web portal carrying the gym's visual identity. Members can purchase packages, manage payment cards, view group class schedules, and review visit history directly from any modern browser.
- **Native Mobile Apps (Coming Soon)**: Dedicated iOS and Android applications providing members with dynamic rotating QR passes for hands-free turnstile entry, trainer booking, and instant push notifications.

## 6. CRM & Customer Experience
- **Member Directory**: Consolidated view of visits, contracts, balance, assigned trainer, locker assignment, and notes.
- **Contract Freezes & Suspensions**: Members or staff can apply contract freezes with configurable limits (e.g. 14 days per 6-month package). Access is suspended during the freeze and automatically reactivated on the resume date.
- **Automated Messaging**: WhatsApp and SMS messaging for:
  - Upcoming renewal notices (3 days and 1 day prior).
  - Inactive member alerts (no visit in 14 days) to prevent churn.
  - Birthday bonuses and personalized promotion vouchers.
  - Check-in receipts and payment confirmation.

## 7. Operations & Ancillary Modules
- **Fitness Bar POS**: Rapid checkout for water, protein shakes, pre-workouts, and accessories, with barcode scanning and integrated drawer support.
- **Locker Management**: Electronic locker assignment, RFID wristband pairing, and monthly locker rentals with automated expiration warnings.
- **Class & Trainer Booking**: Multi-capacity group fitness classes, personal training time slots, and attendance check-in.
- **Multi-Branch Network Support**: Enterprise fitness chains can sync member passes across multiple club locations with real-time pass validation.

## 8. Deployment & Migration
- **Onboarding Duration**: Standard 48-hour turnkey onboarding.
- **Data Migration**: Free automated data ingestion from legacy spreadsheets (Excel, CSV) and third-party software (1C:Fitness, Mindbody, A2, etc.).
- **Staff Training**: Interactive live video or on-site staff walk-through for front-desk receptionists, club managers, and trainers.

## 9. Official Contact Information
- **Website**: https://www.gymos.am
- **Platform**: https://gymos.app
- **General & Enterprise Inquiries**: info@gymos.am
- **Headquarters**: Yerevan, Republic of Armenia