{"id":46394274,"url":"https://github.com/organvm-iii-ergon/gamified-coach-interface","last_synced_at":"2026-03-05T09:15:37.733Z","repository":{"id":323619165,"uuid":"1092641932","full_name":"organvm-iii-ergon/gamified-coach-interface","owner":"organvm-iii-ergon","description":"Gamified coaching system with progress tracking","archived":false,"fork":false,"pushed_at":"2026-02-28T22:51:14.000Z","size":8260,"stargazers_count":0,"open_issues_count":83,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-01T01:45:21.741Z","etag":null,"topics":["coaching","commerce","gamification","organ-iii","organvm","saas"],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/organvm-iii-ergon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-09T02:27:41.000Z","updated_at":"2026-02-28T22:51:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/organvm-iii-ergon/gamified-coach-interface","commit_stats":null,"previous_names":["ivi374forivi/gamified-coach-interface","ivviiviivvi/gamified-coach-interface","labores-profani-crux/gamified-coach-interface","organvm-iii-ergon/gamified-coach-interface"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/organvm-iii-ergon/gamified-coach-interface","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/organvm-iii-ergon%2Fgamified-coach-interface","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/organvm-iii-ergon%2Fgamified-coach-interface/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/organvm-iii-ergon%2Fgamified-coach-interface/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/organvm-iii-ergon%2Fgamified-coach-interface/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/organvm-iii-ergon","download_url":"https://codeload.github.com/organvm-iii-ergon/gamified-coach-interface/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/organvm-iii-ergon%2Fgamified-coach-interface/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30117552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T08:19:04.902Z","status":"ssl_error","status_checked_at":"2026-03-05T08:17:37.148Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coaching","commerce","gamification","organ-iii","organvm","saas"],"created_at":"2026-03-05T09:15:35.061Z","updated_at":"2026-03-05T09:15:37.674Z","avatar_url":"https://github.com/organvm-iii-ergon.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![ORGAN-III: Ergon](https://img.shields.io/badge/ORGAN--III-Ergon-1b5e20?style=flat-square)](https://github.com/organvm-iii-ergon)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square\u0026logo=node.js\u0026logoColor=white)](https://nodejs.org/)\n[![Three.js](https://img.shields.io/badge/Three.js-r160-000000?style=flat-square\u0026logo=three.js)](https://threejs.org/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-15-4169E1?style=flat-square\u0026logo=postgresql\u0026logoColor=white)](https://www.postgresql.org/)\n\n\u003cdiv align=\"center\"\u003e\n\n# Gamified Coach Interface\n\n[![CI](https://github.com/organvm-iii-ergon/gamified-coach-interface/actions/workflows/ci.yml/badge.svg)](https://github.com/organvm-iii-ergon/gamified-coach-interface/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/badge/coverage-pending-lightgrey)](https://github.com/organvm-iii-ergon/gamified-coach-interface)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/organvm-iii-ergon/gamified-coach-interface/blob/main/LICENSE)\n[![Organ III](https://img.shields.io/badge/Organ-III%20Ergon-F59E0B)](https://github.com/organvm-iii-ergon)\n[![Status](https://img.shields.io/badge/status-active-brightgreen)](https://github.com/organvm-iii-ergon/gamified-coach-interface)\n[![TypeScript](https://img.shields.io/badge/lang-TypeScript-informational)](https://github.com/organvm-iii-ergon/gamified-coach-interface)\n\n\n### Legion Command Center — A 3D Holographic Coaching Platform for Fitness Entrepreneurs\n\n*Transform fitness coaching from transactional service delivery into an immersive strategic experience where coaches become commanders and clients become heroes in their own transformation story.*\n\n**[Quick Start](#quick-start)** · **[Architecture](#technical-architecture)** · **[Features](#features--ux-design)** · **[API Configuration](#api-configuration)** · **[Contributing](#contributing)**\n\n\u003c/div\u003e\n\n---\n\n## Product Overview\n\nThe fitness coaching industry is worth over $40 billion, yet roughly 80% of independent coaches fail within two years. They burn 20+ hours per week on administrative overhead — client tracking, content generation, competition research, brand strategy — rather than the transformational coaching work that drew them to the profession. The tools available to them are either glorified spreadsheets or bloated SaaS platforms that treat coaching as an afterthought behind generic project management.\n\n**Gamified Coach Interface** (internally: *Legion Command Center*) takes a fundamentally different approach. It reframes the coaching business as a strategic command center, wrapping serious operational tooling inside an immersive, gamified interface that makes the work of building a coaching empire feel like commanding a mission. The platform integrates AI-powered strategic analysis (via Google Gemini), real-time 3D visualization (via Three.js), and a full-stack backend with quest systems, achievement tracking, community features, and Stripe-powered payments.\n\nThis is not gamification-as-decoration. The game mechanics *are* the core architecture. Every user action has a game-state consequence. Every database table supports progression tracking. The result is a platform where a fitness entrepreneur can define their target customer avatar, design their monetization ladder, craft their brand narrative, research competitors, plan weekly execution, build community structure, and generate content frameworks — all from within a single, narratively coherent interface that rewards strategic discipline with measurable progress.\n\n### The Three Versions\n\nThe project has evolved through three distinct design phases, each still functional:\n\n| Version | Design Language | Technology | Status |\n|---------|----------------|------------|--------|\n| **V1** | Minimal document analysis | Python + python-docx | Complete |\n| **V2** | Retro pixel RPG (Final Fantasy-inspired) | Vanilla JS + Gemini API | Functional |\n| **V3** | Neo-brutalist holographic (Blade Runner 2049) | Three.js + Vite + Gemini API | Primary / Active |\n\n**V3** is the current primary interface — a classified-government-data-analysis aesthetic where the user operates as a Commander accessing strategic intelligence through a cinematic, 3D holographic experience. The design draws direct inspiration from Kanye2049's neo-brutalist interface, translated into the fitness coaching domain: where POTUS OS becomes LEGION OS, where leaked-album artifacts become business intelligence Strategy Cores, and where solution nodes become implementation checklists.\n\n### The Seven Strategic Terminals\n\nAt the conceptual heart of the platform sits a fixed framework of seven strategic terminals — the complete strategy loop for any fitness coaching business:\n\n1. **Hero Class** — Define your target customer avatar (who you serve)\n2. **Loot Table** — Design your monetization ladder (how you earn)\n3. **Propaganda** — Craft your brand narrative (how you're perceived)\n4. **Threat Analysis** — Research competitors and market landscape (what you face)\n5. **Mission Logs** — Plan weekly execution cadence (what you do)\n6. **Guild Charter** — Design community structure and culture (who surrounds you)\n7. **Scriptorium** — Generate content frameworks and templates (what you publish)\n\nThese seven are *sacred structure* — they represent the complete strategic cycle and are not expanded or reduced. Every AI interaction, every module, every quest in the system maps back to one or more of these terminals.\n\n---\n\n## Technical Architecture\n\n### System Overview\n\nThe platform is a full-stack application with three major layers: a 3D frontend, a RESTful backend API, and a PostgreSQL persistence layer, with Google Gemini providing AI capabilities and Stripe handling payments.\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                      CLIENT LAYER                           │\n│                                                             │\n│  legion-v3.html ──► Three.js Scene                          │\n│       │               ├── SceneManager.js (renderer, cam)   │\n│       │               ├── StrategyCore.js (central 3D obj)  │\n│       │               ├── OrbitalNodes.js (5 nav nodes)     │\n│       │               └── main.js (init + module coord)     │\n│       │                                                     │\n│       ├── index.html ──► V2 Command Center (retro pixel)    │\n│       └── client.html ─► V2 Client-Facing Interface         │\n│                                                             │\n├─────────────────────────────────────────────────────────────┤\n│                      API LAYER                              │\n│                                                             │\n│  Express.js (backend/server.js)                             │\n│       ├── Authentication (JWT + bcrypt + refresh tokens)    │\n│       ├── 13 Route Modules:                                 │\n│       │   auth, users, quests, achievements, skills,        │\n│       │   community, strategy, fitness, content,            │\n│       │   payments, analytics, leaderboards, notifications  │\n│       ├── Socket.IO (real-time events: guilds, alerts)      │\n│       ├── Helmet + CORS + rate limiting                     │\n│       └── Winston logging + Morgan HTTP logs                │\n│                                                             │\n├─────────────────────────────────────────────────────────────┤\n│                    PERSISTENCE LAYER                        │\n│                                                             │\n│  PostgreSQL (Sequelize ORM)                                 │\n│       ├── 20+ tables (users, quests, achievements, ...)    │\n│       ├── UUID primary keys throughout                      │\n│       ├── ENUM types for roles, tiers, statuses             │\n│       └── Full-text search on content tables                │\n│                                                             │\n│  Redis (optional cache layer for sessions + leaderboards)   │\n│                                                             │\n├─────────────────────────────────────────────────────────────┤\n│                   EXTERNAL SERVICES                         │\n│                                                             │\n│  Google Gemini API ─── AI strategy generation               │\n│  Stripe API ────────── Payment processing                   │\n│  Socket.IO ─────────── Real-time guild + notification sync  │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### Frontend: Three.js Holographic Interface (V3)\n\nThe V3 frontend is built with **Vite** as the build tool and **Three.js** as the 3D rendering engine. The scene architecture follows a hub-and-spoke model:\n\n- **`SceneManager.js`** — Initializes the Three.js scene, camera, and WebGL renderer. Manages the render loop targeting 60fps on desktop with graceful degradation on less capable hardware.\n- **`StrategyCore.js`** — The central 3D holographic object that the user sees on load. It morphs and glitches in response to API calls (Gemini responses trigger visual distortion effects), reinforcing the narrative that the user is accessing live strategic intelligence.\n- **`OrbitalNodes.js`** — Five navigation nodes orbiting the Strategy Core, each mapped to a functional module: Target Analysis (cyan), Intel Visualization (orange), Field Operations (green), Training Protocols (blue), and Data Archive (grey).\n- **`main.js`** — Application initialization, module coordination, and event routing between 3D scene events and UI overlays.\n\nThe interface follows a scene-based navigation pattern. First-time visitors experience a linear boot sequence (LEGION OS boot screen, holographic login, data hub reveal), while returning users land directly on the hub and can navigate freely between orbital nodes.\n\n### Backend: Express.js API\n\nThe backend is a conventional Express.js application with 13 route modules covering the full surface area of a coaching SaaS platform:\n\n- **Authentication** (`/api/auth`) — Registration, login, JWT issuance, refresh token rotation, password reset. Passwords hashed with bcrypt; tokens stored in PostgreSQL with expiry tracking.\n- **User Management** (`/api/users`) — Profile CRUD, avatar upload (via multer + sharp for image processing), timezone preferences, subscription tier management.\n- **Quest System** (`/api/quests`) — The core gamification engine. Quests are parameterized tasks (daily, weekly, epic, story-arc) with XP rewards, completion conditions, and chain dependencies.\n- **Achievements** (`/api/achievements`) — Milestone-based unlocks triggered by cumulative quest completion, streak maintenance, or special conditions.\n- **Skills** (`/api/skills`) — Skill tree progression where XP earned in specific categories (marketing, content, client management, etc.) unlocks deeper capabilities.\n- **Community** (`/api/community`) — Guild creation, membership, chat (via Socket.IO), and shared leaderboards. Guilds provide accountability structure for coaches.\n- **Strategy** (`/api/strategy`) — The Gemini AI integration endpoint. Accepts strategy parameters (target avatar, business model, competitive landscape), forwards to Gemini with the 7-Terminal framework as system context, and returns structured strategic intelligence.\n- **Fitness** (`/api/fitness`) — Workout logging, program templates, and client progress tracking — the domain-specific layer that distinguishes this from a generic business tool.\n- **Content** (`/api/content`) — Content calendar, template library, and AI-assisted content generation mapped to the Scriptorium terminal.\n- **Payments** (`/api/payments`) — Stripe integration for subscription management across five tiers: Free, Potion, Core Quest, Raid, and Mastermind.\n- **Analytics** (`/api/analytics`) — Usage metrics, engagement tracking, and exportable reports (PDF generation via pdfkit).\n- **Leaderboards** (`/api/leaderboards`) — XP-based rankings with Redis caching for performance at scale.\n- **Notifications** (`/api/notifications`) — Real-time push via Socket.IO and persistent notification storage for offline users.\n\n### Database Schema\n\nThe PostgreSQL schema uses UUIDs throughout and is organized around the gamification-as-infrastructure principle. Key design decisions:\n\n- **Subscription tiers as ENUM** (`free`, `potion`, `core_quest`, `raid`, `mastermind`) — the tier names reflect the game metaphor and map to Stripe price IDs.\n- **XP is tracked at multiple levels** — per-user aggregate XP, per-skill category XP, per-quest XP awards — enabling both global leaderboards and skill-specific progression.\n- **Quests support chain dependencies** — a quest can require completion of predecessor quests, enabling story-arc narratives (e.g., \"Complete Hero Class terminal\" requires completing 5 sub-quests defining your avatar).\n- **Guilds with role-based access** — guild members, officers, and leaders have different permission levels, supporting real coaching cohort structures.\n- **Full audit trail** — `created_at` and `updated_at` timestamps on every table, with soft-delete support via status ENUMs rather than destructive deletion.\n\n### Document Analysis System (V1)\n\nA Python-based strategic document ingestion pipeline (`scripts/analyze_docs.py`) that scans `.docx` files, extracts key topics and statistics, categorizes content by theme (fitness, business, gamification), and generates a recommended development path. This was the project's first iteration and remains functional as a standalone tool.\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js** 18+ and npm 9+\n- **PostgreSQL** 15+ (for backend features)\n- **Python** 3.11+ (optional, for document analysis)\n- A modern browser with WebGL support\n- (Optional) Google Gemini API key for AI-powered strategy generation\n- (Optional) Redis for leaderboard caching\n\n### Frontend Only (V3 Holographic Interface)\n\n```bash\n# Clone the repository\ngit clone https://github.com/organvm-iii-ergon/gamified-coach-interface.git\ncd gamified-coach-interface\n\n# Install frontend dependencies\nnpm install\n\n# Start the Vite development server\nnpm run dev\n\n# Open http://localhost:3000/legion-v3.html\n```\n\nThe V3 holographic interface will load with the LEGION OS boot sequence. AI strategy generation requires a Gemini API key (see [API Configuration](#api-configuration) below); all other features work without external services.\n\n### Full Stack (Frontend + Backend)\n\n```bash\n# Clone and install all dependencies\ngit clone https://github.com/organvm-iii-ergon/gamified-coach-interface.git\ncd gamified-coach-interface\nnpm run install:all\n\n# Configure the backend environment\ncp backend/.env.example backend/.env\n# Edit backend/.env with your PostgreSQL credentials, JWT secret, Stripe keys, etc.\n\n# Run database migrations and seed data\ncd backend\nnpm run migrate\nnpm run seed\ncd ..\n\n# Start both frontend and backend\n# Terminal 1: Frontend\nnpm run dev\n\n# Terminal 2: Backend\ncd backend\nnpm run dev\n```\n\n### Document Analysis (V1 Python Tool)\n\n```bash\n# Install Python dependencies\npip install -r requirements.txt\n\n# Run the document analyzer\npython3 scripts/analyze_docs.py\n```\n\nThe analyzer scans the repository for `.docx` source documents, extracts themes and statistics, and outputs a categorized development roadmap.\n\n### Production Build\n\n```bash\n# Build optimized frontend assets\nnpm run build\n\n# Preview the production build\nnpm run preview\n\n# Start backend in production mode\ncd backend\nNODE_ENV=production npm start\n```\n\n### Running Tests\n\n```bash\n# All tests (frontend + backend)\nnpm run test:all\n\n# Frontend tests only (Vitest)\nnpm run test:frontend\n\n# Backend tests only (Jest with coverage)\nnpm run test:backend\n```\n\n---\n\n## Features \u0026 UX Design\n\n### V3 Holographic Interface Modules\n\nThe V3 interface organizes functionality into five orbital modules, each accessible by clicking its corresponding navigation node or using the bottom menu bar:\n\n#### 1. Target Analysis (Cyan Node) — Strategy Forge\n\nThe primary strategy generation module. Users fill out structured parameters — target customer avatar, transformation goals, competitive landscape — and the system forwards these to Google Gemini with the 7-Terminal framework as system context. The AI returns structured strategic intelligence: actionable checklists, competitive positioning frameworks, and decision matrices. A fallback analysis engine operates without an API key for offline use.\n\nWhen the AI responds, the central Strategy Core object *visually distorts and glitches*, reinforcing the narrative that live intelligence is being processed. Results are saveable to persistent workspaces — a core data-sovereignty principle: every strategic decision, AI conversation, and generated plan belongs to the user.\n\n#### 2. Intel Visualization (Orange Node) — Market Landscape\n\nMarket analysis and competitive intelligence visualization. Displays the coaching landscape as visual data maps, helping coaches identify positioning opportunities and competitive gaps. Currently renders static market data with plans for live data integration.\n\n#### 3. Field Operations (Green Node) — Operational Dashboard\n\nThe day-to-day command center for active client management, quest tracking, and operational metrics. Surfaces the most urgent tasks and streaks, integrating with the backend quest and analytics APIs to provide a real-time operational picture.\n\n#### 4. Training Protocols (Blue Node) — Knowledge Base\n\nAn educational module containing business strategy frameworks, coaching methodology references, and the theoretical foundations that inform the platform's design. Content is structured as \"training missions\" — consumable modules that award XP on completion.\n\n#### 5. Data Archive (Grey Node) — Strategic Document Repository\n\nAccess point for all analyzed strategic documents, AI-generated strategy reports, and reference materials. Integrates with the V1 document analysis system to surface insights from the original source documents that informed the platform's development.\n\n### Gamification Engine\n\nThe gamification layer is not a cosmetic overlay — it is the structural backbone of the user experience:\n\n- **XP and Leveling** — Every meaningful action (completing a strategy session, logging a workout, publishing content, maintaining a streak) awards experience points. XP accumulates toward level thresholds, with each level unlocking new titles (Recruit, Centurion, Commander, Imperator, etc.) and platform capabilities.\n- **Quest System** — Tasks are modeled as quests with defined objectives, XP rewards, and chain dependencies. Daily quests maintain engagement cadence; weekly quests drive strategic milestones; epic quests represent major business achievements (first paying client, first 50 subscribers, etc.).\n- **Achievement Badges** — Milestone-based unlocks that serve as portfolio evidence of coaching business development. Achievements are visible on profiles and shareable.\n- **Streaks and Consistency** — Login streaks and activity streaks with escalating XP multipliers. The system tracks both current and longest streak, creating a persistent motivation mechanic.\n- **Skill Trees** — XP earned in specific categories (marketing, content creation, client management, community building) feeds into per-skill progression, making the coach's growing expertise visible and trackable.\n- **Leaderboards** — Guild-scoped and global leaderboards with Redis-cached rankings, fostering healthy competition between coaching cohorts.\n- **Subscription Tiers** — Five tiers (Free, Potion, Core Quest, Raid, Mastermind) gate advanced features behind Stripe-managed subscriptions, with each tier name reinforcing the game metaphor.\n\n### Three Core Design Principles\n\nEvery feature decision is filtered through these immutable principles (documented fully in [`docs/NORTH_STAR.md`](docs/NORTH_STAR.md)):\n\n1. **Gamification as Infrastructure, Not Decoration** — If a feature cannot be gamified, question whether it belongs. Game mechanics are not applied after the fact; they *are* the architecture. A workout log is a quest completion. A calendar is a battle timeline. A content plan is a scriptorium mission.\n\n2. **AI as Strategic Advisor, Not Content Generator** — Gemini integration must help coaches *decide*, not just *read*. Every AI response is contextualized within the 7-Terminal framework, building a persistent knowledge graph rather than generating throwaway text. If an AI feature only produces content for consumption, it is rejected or redesigned.\n\n3. **Data Sovereignty: The User Owns Their Strategy** — All AI conversations, generated plans, and strategic decisions are exportable (JSON, Markdown, PDF). No vendor lock-in. No training on user data. Data structures are open and documented.\n\n---\n\n## API Configuration\n\n### Gemini AI Integration\n\nTo enable AI-powered strategy generation in the V3 interface:\n\n1. Obtain a Gemini API key from [Google AI Studio](https://makersuite.google.com/app/apikey)\n2. Navigate to the **Target Analysis** module (cyan node)\n3. Fill out the strategy parameters form\n4. Click **INITIATE STRATEGIC ANALYSIS**\n5. Enter your API key when prompted (saved to local storage for future sessions)\n\nThe key is stored client-side only and never transmitted to the backend. For backend AI features, configure `GEMINI_API_KEY` in `backend/.env`.\n\n### Stripe Payments\n\nConfigure Stripe for subscription management:\n\n```env\nSTRIPE_SECRET_KEY=sk_live_...\nSTRIPE_WEBHOOK_SECRET=whsec_...\nSTRIPE_PRICE_FREE=price_...\nSTRIPE_PRICE_POTION=price_...\nSTRIPE_PRICE_CORE_QUEST=price_...\nSTRIPE_PRICE_RAID=price_...\nSTRIPE_PRICE_MASTERMIND=price_...\n```\n\n### Environment Variables\n\nCopy `backend/.env.example` to `backend/.env` and configure:\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `DATABASE_URL` | PostgreSQL connection string | Yes |\n| `JWT_SECRET` | Secret for signing JWT tokens | Yes |\n| `JWT_REFRESH_SECRET` | Secret for refresh tokens | Yes |\n| `CORS_ORIGIN` | Allowed frontend origins (comma-separated) | Yes |\n| `GEMINI_API_KEY` | Google Gemini API key | Optional |\n| `STRIPE_SECRET_KEY` | Stripe secret key | Optional |\n| `REDIS_URL` | Redis connection string for caching | Optional |\n| `PORT` | Backend server port (default: 5000) | No |\n\nFrontend environment variables (Gemini key, backend URL) are configured in a root `.env` file — copy and fill before running `npm run dev`.\n\n---\n\n## Project Structure\n\n```\ngamified-coach-interface/\n├── legion-v3.html              # V3 holographic interface (primary entry point)\n├── index.html                  # V2 retro command center\n├── client.html                 # V2 client-facing interface\n│\n├── src/                        # V3 frontend source\n│   ├── main.js                 # Application init + module coordination\n│   ├── SceneManager.js         # Three.js scene, camera, renderer\n│   ├── StrategyCore.js         # Central 3D holographic object\n│   ├── OrbitalNodes.js         # 5 orbital navigation nodes\n│   └── tests/                  # Frontend smoke tests (Vitest)\n│\n├── backend/                    # Express.js API\n│   ├── server.js               # Server entry point\n│   ├── config/                 # Database configuration\n│   ├── controllers/            # Request handlers\n│   ├── middleware/              # Auth, error handling, rate limiting\n│   ├── migrations/             # Sequelize migrations\n│   ├── models/                 # Sequelize ORM models\n│   ├── routes/                 # 13 API route modules\n│   ├── services/               # Business logic (analytics, etc.)\n│   ├── utils/                  # Logger, validators, formatters\n│   ├── database/               # SQL schema + seed data\n│   └── tests/                  # Jest test suite\n│\n├── scripts/                    # Automation + document analysis\n│   ├── analyze_docs.py         # V1 document ingestion tool\n│   └── manage_vscode_extensions.sh\n│\n├── prototypes/                 # Legacy HTML experiments\n│   ├── Rok_Gym.html            # Early fitness tracking prototype\n│   ├── client.html             # Early client interface\n│   └── legion-command-center-evolved.html\n│\n├── docs/                       # Comprehensive documentation\n│   ├── NORTH_STAR.md           # Guiding principles + 7-Terminal framework\n│   ├── INDEX.md                # Documentation map\n│   ├── architecture/           # Technical architecture docs\n│   ├── design-specs/           # V3 design specification\n│   ├── operational/            # Status, TODO, merge history\n│   ├── research/               # Market research + Gemini drafts\n│   └── source-documents/       # Original .docx strategy documents\n│\n├── verification/               # Testing + accessibility verification\n├── vite.config.js              # Vite build configuration\n├── vitest.config.js            # Vitest test configuration\n├── package.json                # Frontend dependencies (Three.js, Vite)\n├── requirements.txt            # Python dependencies (python-docx)\n│\n├── ARCHITECTURE.md             # Architecture guide\n├── CONTRIBUTING.md             # Contribution guidelines\n├── CODE_OF_CONDUCT.md          # Community standards\n├── SECURITY.md                 # Security policy\n└── LICENSE                     # MIT License\n```\n\n---\n\n## Cross-Organ Context\n\nThis repository sits within **ORGAN-III (Ergon)** — the Commerce organ of the eight-organ [organvm](https://github.com/meta-organvm) creative-institutional system. ORGAN-III houses all product-facing repositories: SaaS platforms, B2B tools, B2C applications, and internal tooling.\n\nGamified Coach Interface draws on theoretical foundations developed in **ORGAN-I (Theoria)**, where recursive systems theory, ontological design patterns, and epistemological frameworks are explored as first-class research subjects. The gamification-as-infrastructure principle — the idea that game mechanics should be structural rather than decorative — originates in ORGAN-I's work on systems that produce emergent behavior through layered rule sets. The 7-Terminal framework similarly reflects ORGAN-I thinking about complete conceptual loops and fixed-point structures.\n\nThe platform's public-facing narrative and build-in-public documentation live in **ORGAN-V (Logos)**, where the process of constructing this system is itself a subject of reflective writing. The community features (guilds, shared leaderboards, coaching cohorts) connect conceptually to **ORGAN-VI (Koinonia)**, the Community organ that explores how groups form, sustain, and govern themselves.\n\n| Organ | Relationship | Example |\n|-------|-------------|---------|\n| [ORGAN-I: Theoria](https://github.com/organvm-i-theoria) | Theoretical foundations | Recursion patterns, gamification-as-infrastructure principle |\n| [ORGAN-II: Poiesis](https://github.com/organvm-ii-poiesis) | Aesthetic language | Neo-brutalist design system, holographic UI vocabulary |\n| [ORGAN-V: Logos](https://github.com/organvm-v-logos) | Public process | Build-in-public essays on platform development |\n| [ORGAN-VI: Koinonia](https://github.com/organvm-vi-koinonia) | Community patterns | Guild mechanics, cohort accountability structures |\n\n---\n\n## Related Work\n\nWithin the ORGAN-III ecosystem, Gamified Coach Interface sits alongside several related commercial repositories:\n\n- **[public-record-data-scrapper](https://github.com/organvm-iii-ergon/public-record-data-scrapper)** — Data scraping infrastructure for public records, demonstrating a different flavor of ORGAN-III's commercial orientation (B2B data tooling vs. B2C SaaS).\n- **[tab-bookmark-manager](https://github.com/organvm-iii-ergon/tab-bookmark-manager)** — Browser extension for bookmark management, representing ORGAN-III's internal-tooling category.\n- **[virgil-training-overlay](https://github.com/organvm-iii-ergon/virgil-training-overlay)** — AI training overlay system with thematic connections to the coaching and education domain.\n\n---\n\n## Keyboard Shortcuts\n\n| Key | Action |\n|-----|--------|\n| `ESC` | Close active terminal or modal |\n| Click | Navigate between orbital nodes and menu items |\n\n---\n\n## Contributing\n\nContributions are welcome. Please review these resources before submitting a pull request:\n\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** — Development setup, code style, PR process, and testing requirements\n- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — Community standards and expected behavior\n- **[ARCHITECTURE.md](ARCHITECTURE.md)** — Full architecture guide and documentation map\n- **[SECURITY.md](SECURITY.md)** — Vulnerability reporting policy\n\n### Quick Contribution Steps\n\n```bash\n# Fork and clone\ngit clone https://github.com/\u003cyour-username\u003e/gamified-coach-interface.git\n\n# Create a feature branch\ngit checkout -b feature/your-feature-name\n\n# Install all dependencies\nnpm run install:all\n\n# Make changes, then run tests\nnpm run test:all\n\n# Commit and push\ngit add .\ngit commit -m \"Add your feature description\"\ngit push origin feature/your-feature-name\n\n# Open a pull request against main\n```\n\n---\n\n## License\n\nThis project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for full terms.\n\n---\n\n## Author\n\n**[@4444j99](https://github.com/4444j99)**\n\nPart of the [organvm](https://github.com/meta-organvm) eight-organ creative-institutional system.\nORGAN-III: Ergon — Commerce, products, and applied systems.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forganvm-iii-ergon%2Fgamified-coach-interface","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forganvm-iii-ergon%2Fgamified-coach-interface","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forganvm-iii-ergon%2Fgamified-coach-interface/lists"}