diff --git a/docs/WEB_VS_CLIENT_SYSTEMS.md b/docs/WEB_VS_CLIENT_SYSTEMS.md deleted file mode 100644 index ddd5003..0000000 --- a/docs/WEB_VS_CLIENT_SYSTEMS.md +++ /dev/null @@ -1,926 +0,0 @@ -# Web vs Client Feature Distribution - -**Version:** 1.0 -**Last Updated:** November 17, 2025 -**Status:** Architectural Decision Document - ---- - -## Overview - -This document defines the feature distribution strategy between **Public Web Frontend** (`/public_web`) and **Godot Game Client** (`/godot_client`). It outlines what features belong in each frontend, security considerations, and implementation priorities. - -**Core Principle:** Both frontends are **thin clients** that make HTTP calls to the API backend. The API is the single source of truth for all business logic, data persistence, and validation. - ---- - -## Architecture Pattern - -``` -┌─────────────────────────────────────────────────────────────┐ -│ User Access │ -├──────────────────────────┬──────────────────────────────────┤ -│ │ │ -│ Public Web Frontend │ Godot Game Client │ -│ (Flask + Jinja2) │ (Godot 4.5) │ -│ │ │ -│ - Account Management │ - Gameplay Experience │ -│ - Character Viewing │ - Combat & Quests │ -│ - Marketplace │ - Real-time Multiplayer │ -│ - Community │ - Inventory & Equipment │ -│ │ │ -└──────────────────────────┴──────────────────────────────────┘ - │ - ▼ - ┌────────────────────┐ - │ API Backend │ - │ (Flask REST) │ - │ │ - │ - Business Logic │ - │ - Validation │ - │ - Data Persistence │ - │ - AI Integration │ - └────────────────────┘ - │ - ▼ - ┌────────────────────┐ - │ Appwrite DB │ - │ + Redis Cache │ - └────────────────────┘ -``` - -**Key Points:** -- Both frontends are **untrusted clients** - API validates everything -- No business logic in frontends (only UI/UX) -- No direct database access from frontends -- API enforces permissions, rate limits, tier restrictions - ---- - -## Feature Distribution Strategy - -### Decision Framework - -When deciding where a feature belongs, consider: - -1. **Security Sensitivity** - Payment/account changes → Web only -2. **Gameplay Integration** - Combat/quests → Game only -3. **Accessibility** - Planning/browsing → Web preferred -4. **User Experience** - Visual/immersive → Game preferred -5. **Performance** - Real-time updates → Game preferred -6. **SEO/Marketing** - Public content → Web preferred - ---- - -## Public Web Frontend Features - -The web frontend serves as the **Management Plane** - where players manage their account, characters, and community presence outside of active gameplay. - -### ✅ Core Account Management (Security-Critical) - -**Authentication & Security:** -- User registration with email verification -- Login with session management -- Password reset flow (email-based) -- Change password (requires re-authentication) -- Change email address (with verification) -- Two-Factor Authentication (2FA) setup -- View active sessions (device management) -- Login history and security audit log -- Account deletion (GDPR compliance) - -**Why Web?** -- Security-critical operations require robust email flows -- PCI/GDPR compliance easier on web -- Better audit trails with server logs -- Standard user expectation (manage accounts in browsers) -- HTTPS, CSP headers, secure cookie handling - -### ✅ Subscription & Payment Management - -**Billing Features:** -- View current subscription tier -- Upgrade/downgrade between tiers (Free, Basic, Premium, Elite) -- Payment method management (add/remove cards) -- Billing history and invoices -- Cancel subscription -- Gift code redemption -- Referral program tracking - -**Why Web?** -- **PCI DSS compliance** - Never handle payments in game clients -- Standard payment gateways (Stripe, PayPal) are web-first -- Easier to secure against client-side tampering -- Legal/regulatory requirements (receipts, invoices) -- Integration with Stripe Customer Portal - -**Security:** -- No payment data stored in database (Stripe handles) -- Webhook verification for subscription changes -- Transaction logging for audit compliance - -### ✅ Character Management (Viewing & Light Editing) - -**Character Features:** -- **Character Gallery** - View all characters with stats, equipment, level, achievements -- **Character Detail View** - Full character sheet (read-only) -- **Character Comparison** - Side-by-side stat comparison (useful for planning builds) -- **Character Renaming** - Simple text field edit -- **Character Deletion** - Soft delete with confirmation modal -- **Skill Tree Viewer** - Read-only interactive skill tree (planning builds) - -**Why Web?** -- Accessible from anywhere (phone, work, tablet) -- Good for planning sessions while away from desktop -- Faster load times than booting game client -- Industry standard: WoW Armory, FFXIV Lodestone, D&D Beyond - -**Note:** Character **creation** wizard can be on web OR game (see recommendations below) - -### ✅ Marketplace (Full-Featured Trading Hub) - -**Marketplace Features:** -- **Browse Listings** - Search, filter, sort with pagination -- **Advanced Search** - Filter by item type, rarity, level, price range -- **Place Bids** - Auction bidding system with bid history -- **Buyout** - Instant purchase at buyout price -- **Create Listing** - List items for auction or fixed price -- **My Listings** - View/cancel your active listings -- **My Bids** - View/manage your active bids -- **Transaction History** - Full audit trail of purchases/sales -- **Price Analytics** - Charts, market trends, price history -- **Watchlist** - Save listings to watch later -- **Notification Preferences** - Email/in-game alerts for auction wins/outbid - -**Why Web?** -- Better for serious trading (multiple tabs, spreadsheets, price comparison) -- Data visualization for market trends (charts work better on web) -- Pagination-friendly (hundreds of listings) -- Can browse while at work/away from game -- SEO benefits (public listings can be indexed) - -**Note:** Game client should have **light marketplace access** for convenience (quick browse/buy during gameplay) - -### ✅ Community & Content - -**Community Features:** -- **Dev Blog** - Patch notes, announcements, event schedules -- **Game News** - Latest updates, maintenance windows, new features -- **Forums** - Player discussions (or link to Discord/Reddit) -- **Leaderboards** - Global rankings, seasonal standings, category leaderboards -- **Guild Directory** - Browse guilds, recruitment listings, guild pages -- **Player Profiles** - Public character pages (if user enables) -- **Session Replays** - View past session logs (markdown export from API) -- **Knowledge Base** - Game wiki, guides, FAQs, tutorials -- **Feedback/Suggestions** - Submit feedback, vote on features - -**Why Web?** -- **SEO benefits** - Google can index news, guides, wiki pages (marketing) -- Accessible to non-players (prospect research before signing up) -- Easier content updates (no client patches required) -- Standard for all MMOs/online games (WoW, FFXIV, GW2, etc.) -- Community engagement outside of gameplay - -### ✅ Analytics & Progress Tracking - -**Dashboard Features:** -- **Account Stats** - Total playtime, characters created, sessions played -- **Character Progress** - XP charts, gold history, level progression timeline -- **Combat Analytics** - Win/loss rate, damage dealt, kills, deaths -- **Achievement Tracker** - Progress toward achievements, completion percentage -- **Quest Log** - View active/completed quests across all characters -- **Collection Tracker** - Items collected, rare drops, completionist progress - -**Why Web?** -- Always accessible (check progress on phone) -- Better for data visualization (charts, graphs, timelines) -- Doesn't clutter game UI -- Can share stats publicly (profile pages) - -### ✅ Support & Help - -**Support Features:** -- **Help Desk** - Submit support tickets, track status -- **FAQ / Knowledge Base** - Searchable help articles -- **Contact Form** - Direct contact with support team -- **Bug Reports** - Submit bug reports with screenshots -- **Email Preferences** - Newsletter subscriptions, notification settings - -**Why Web?** -- Standard support workflow (ticket systems) -- Easier to attach screenshots/logs -- Can access while game is broken -- GDPR compliance (manage email consent) - -### ✅ Guild Management Hub (Future Feature) - -**Guild Features:** -- **Create Guild** - Setup guild with name, description, emblem -- **Manage Guild** - Edit details, set permissions, manage roster -- **Guild Bank** - View/manage shared resources -- **Guild Events** - Schedule raids, events with calendar integration -- **Guild Permissions** - Role-based access control -- **Recruitment** - Post recruitment listings to directory - -**Why Web?** -- Guild management is administrative (not gameplay) -- Better UX for roster management (tables, sorting) -- Calendar integration works better on web -- Officers can manage guild without booting game - ---- - -## Godot Game Client Features - -The game client serves as the **Experience Plane** - where players engage with gameplay, combat, story, and real-time interactions. - -### ✅ Core Gameplay - -**Gameplay Features:** -- **Character Creation** - Full visual wizard with 3D character previews -- **Combat System** - Turn-based combat UI with animations, effects, sound -- **Quest System** - Quest tracking, objectives, turn-ins, rewards -- **Story Progression** - AI DM interactions, narrative choices, action prompts -- **Exploration** - World map navigation, location discovery, fast travel -- **NPC Interactions** - Dialogue trees, shop browsing, quest givers -- **Session Management** - Join/create sessions, invite players, session state - -**Why Game?** -- Rich UI/UX (animations, particle effects, sound design) -- Immersive experience (3D environments, music, atmosphere) -- Real-time interactions with AI DM -- This is what players launch the game for - -### ✅ Inventory & Equipment Management - -**Inventory Features:** -- **Inventory UI** - Drag-drop interface, auto-sort, filtering -- **Equipment System** - Character sheet, equip/unequip with visual updates -- **Item Tooltips** - Detailed stats, stat comparisons (current vs new) -- **Item Usage** - Consume potions, activate items, combine items -- **Loot System** - Loot drops, auto-loot settings, loot rolling (multiplayer) - -**Why Game?** -- Drag-drop is better in native UI than web -- Visual feedback (character model updates when equipped) -- Tight integration with combat/gameplay -- Real-time item usage during combat - -### ✅ Social & Multiplayer - -**Social Features:** -- **Party Formation** - Invite players to party, manage party composition -- **Chat System** - Party chat, global chat, whispers, guild chat -- **Multiplayer Sessions** - Real-time session joining, turn coordination -- **Emotes** - Character animations, quick messages -- **Friend List** - Add friends, see online status, invite to party -- **Voice Chat Integration** - Discord Rich Presence or in-game voice - -**Why Game?** -- Real-time communication during gameplay -- WebSocket integration for live updates (Appwrite Realtime) -- Better performance for rapid message updates -- Social features enhance gameplay immersion - -### ✅ Character Customization - -**Customization Features:** -- **Appearance Editor** - Visual character customization (face, hair, body type) -- **Skill Tree** - Interactive skill unlocking with visual tree UI -- **Talent Respec** - Preview changes, confirm spend, visual feedback -- **Cosmetics** - Apply skins, mount cosmetics, visual effects -- **Character Sheet** - Live stat updates, equipment preview - -**Why Game?** -- Visual feedback (see changes immediately on 3D model) -- Integrated with character rendering engine -- Better UX for complex skill trees (zoom, pan, tooltips) -- Drag-drop equipment for easy comparison - -### ✅ Combat & Abilities - -**Combat Features:** -- **Attack System** - Target selection, attack animations, damage numbers -- **Spell Casting** - Spell targeting, visual effects, cooldown tracking -- **Item Usage** - Combat items (potions, scrolls), inventory shortcuts -- **Defensive Actions** - Dodge, block, defend with animations -- **Combat Log** - Real-time combat text log with color coding -- **Status Effects** - Visual indicators for buffs/debuffs, duration tracking - -**Why Game?** -- Animations, sound effects, particle systems -- Real-time feedback during combat -- Immersive combat experience -- Tight integration with game loop - -### ✅ NPC Shops & Marketplace (Light Access) - -**In-Game Commerce:** -- **NPC Shops** - Browse shop inventory, purchase items, sell loot -- **Marketplace (Quick Access)** - Simple search, quick buy, notifications -- **Auction Alerts** - Pop-up notifications for auction wins/outbid -- **Transaction Confirmation** - In-game purchase confirmations - -**Why Game?** -- Convenience during gameplay (buy potions before dungeon) -- Quick transactions without alt-tabbing -- NPC shops are part of world immersion - -**Note:** Serious trading should still happen on web (better UX for market analysis) - -### ✅ Map & Navigation - -**Navigation Features:** -- **World Map** - Interactive map with zoom, fog of war -- **Minimap** - Real-time position tracking during exploration -- **Waypoints** - Set custom waypoints, quest markers -- **Fast Travel** - Teleport to discovered locations -- **Location Discovery** - Reveal map as you explore - -**Why Game?** -- Real-time position updates during movement -- Integration with 3D world rendering -- Better performance for map rendering - ---- - -## Features That Should Be in BOTH (Different UX) - -Some features benefit from being accessible in both frontends with different user experiences: - -### 🔄 Marketplace -- **Web:** Full-featured trading hub (serious trading, market analysis, price charts) -- **Game:** Quick access (buy potions, check if auction won, browse while waiting) - -### 🔄 Character Viewing -- **Web:** Planning builds (read-only skill trees, stat calculators, gear comparisons) -- **Game:** Active gameplay (equip items, unlock skills, use abilities) - -### 🔄 News & Events -- **Web:** Read patch notes, browse dev blog, event calendars -- **Game:** In-game notifications (event starting soon, new patch available) - -### 🔄 Achievements -- **Web:** Achievement tracker, progress bars, leaderboards, collection view -- **Game:** Achievement pop-ups, unlock notifications, sound effects - -### 🔄 Friends & Social -- **Web:** Manage friend list, send friend requests, view profiles -- **Game:** See online status, invite to party, send messages - ---- - -## Security Best Practices - -### 🔒 Web-Only (High Security Operations) - -These features MUST be web-only for security/compliance reasons: - -1. **Payment Processing** - - PCI DSS compliance is easier on web - - Standard payment gateways (Stripe, PayPal) are web-first - - Easier to secure against client-side tampering - - Audit trails for regulatory compliance - - **NEVER handle payment info in game client** - -2. **Password Management** - - Password reset flows require email verification - - Password change requires re-authentication - - Web is more secure (HTTPS, CSP headers, no client tampering) - - **NEVER allow password changes in game client** - -3. **Email/Account Recovery** - - Email verification links (click to verify in browser) - - 2FA setup (QR codes for authenticator apps) - - Backup code generation and storage - - **Web-based flows are standard** - -4. **Account Deletion / Critical Operations** - - Requires email confirmation (prevent accidental deletion) - - Legal compliance (GDPR right to deletion, data export) - - Audit trail requirements - - **Too risky for game client** - -### 🎮 Game Client (Lower Security Risk) - -These operations are safe in game client (with API validation): - -- Gameplay actions (combat, quests, item usage) -- Character creation (not security-critical) -- Inventory management (server validates all transactions) -- Social features (chat, parties - API handles rate limits) - -**Why Safe?** -- All validated server-side by API -- Game client is just a UI (thin client architecture) -- Cheating attempts fail at API validation layer -- API enforces permissions, tier limits, rate limits - -### 🔐 Security Architecture Principle - -``` -[Untrusted Client] → [API Validates Everything] → [Database] -``` - -**Both frontends are untrusted:** -- Never trust client-side data -- API validates all inputs (sanitize, type check, permission check) -- API enforces business rules (tier limits, cooldowns, costs) -- Database transactions ensure data integrity - ---- - -## Security Checklist for Web Frontend - -When implementing web features, ensure: - -### Authentication & Sessions -- [ ] HTTPS everywhere (Cloudflare, Let's Encrypt, SSL certificate) -- [ ] HTTP-only cookies for sessions (JavaScript cannot access) -- [ ] Secure flag on cookies (HTTPS only in production) -- [ ] SameSite: Lax or Strict (CSRF protection) -- [ ] Session expiration (24 hours normal, 30 days remember-me) -- [ ] Session regeneration after login (prevent session fixation) - -### Input Validation & Protection -- [ ] CSRF protection on all forms (Flask-WTF) -- [ ] Input validation and sanitization (prevent XSS, SQLi) -- [ ] Content Security Policy (CSP) headers -- [ ] Rate limiting on sensitive endpoints (login, registration, password reset) -- [ ] CAPTCHA on registration/login (prevent bots) - -### Payment Security -- [ ] Use Stripe/PayPal hosted checkout (no card data in your DB) -- [ ] Verify webhook signatures (prevent fake payment confirmations) -- [ ] PCI DSS compliance (use certified payment processors) -- [ ] Transaction logging for audit compliance - -### Account Security -- [ ] Two-Factor Authentication (2FA) support (TOTP, backup codes) -- [ ] Email verification on registration -- [ ] Email confirmation for critical operations (password change, email change) -- [ ] Account lockout after N failed login attempts (5-10 attempts) -- [ ] Login history tracking (IP, device, timestamp) -- [ ] Security event notifications (new device login, password changed) - -### Data Protection & Compliance -- [ ] GDPR compliance (data export, right to deletion) -- [ ] Privacy policy and terms of service -- [ ] Cookie consent banner (EU requirements) -- [ ] Data encryption at rest (database encryption) -- [ ] Data encryption in transit (TLS 1.2+ for API calls) -- [ ] Secure password storage (bcrypt, Argon2) - -### HTTP Security Headers -- [ ] Strict-Transport-Security (HSTS) -- [ ] X-Content-Type-Options: nosniff -- [ ] X-Frame-Options: DENY (prevent clickjacking) -- [ ] X-XSS-Protection: 1; mode=block -- [ ] Referrer-Policy: strict-origin-when-cross-origin - -### Logging & Monitoring -- [ ] Audit logging (who did what, when) -- [ ] Error tracking (Sentry, Rollbar) -- [ ] Security event alerts (failed logins, suspicious activity) -- [ ] Uptime monitoring (status page) - ---- - -## Industry Examples & Best Practices - -### World of Warcraft (Blizzard) - -**Web (Battle.net):** -- Account management (register, login, 2FA, password reset) -- Shop (game time, expansions, mounts, pets) -- Armory (character profiles, gear, achievements) -- News (patch notes, events, hotfixes) -- Forums (community discussions) -- Guild finder - -**Game Client:** -- All gameplay (quests, combat, exploration) -- Character customization (transmog, talents) -- Auction house (but also web armory for viewing) -- In-game shop (quick access to mounts/pets) - -**Key Insight:** Players use web for planning (checking gear, reading news) and game for playing - ---- - -### Final Fantasy XIV (Square Enix) - -**Web (Lodestone + Mog Station):** -- Lodestone: News, character profiles, free company search, event calendar -- Mog Station: Account management, subscription, shop (mounts, cosmetics) -- Market board history and price trends - -**Game Client:** -- All gameplay -- Retainer market board (player-driven economy) -- Glamour system (cosmetics) -- In-game shop access - -**Key Insight:** Separate web properties for community (Lodestone) vs account (Mog Station) - ---- - -### Path of Exile (Grinding Gear Games) - -**Web:** -- Official trade marketplace (advanced search, price indexing) -- Account management (login, 2FA, linked accounts) -- News and patch notes -- Build guides and community wiki -- Passive skill tree planner - -**Game Client:** -- All gameplay (combat, loot, skill gems) -- In-game item searching (but serious traders use web) -- Hideout customization -- MTX shop access - -**Key Insight:** Community created trade tools before official web version (PoE.trade) - web is essential for complex economies - ---- - -### EVE Online (CCP Games) - -**Web:** -- Extensive market tools (price history, regional comparison) -- Killboards (combat logs, ship losses) -- Contract browsing (item contracts, courier contracts) -- Account management and subscription -- Skill planner - -**Game Client:** -- Flying ships, combat, exploration -- Quick market trades (local market) -- Contract management -- Corporation (guild) management - -**Key Insight:** EVE's complexity REQUIRES web tools - players use spreadsheets alongside web for market trading - ---- - -### D&D Beyond (Wizards of the Coast) - -**Web:** -- Character builder (digital character sheets) -- Campaign management (DM tools) -- Rules reference (searchable rules, spells, items) -- Marketplace (digital books, adventures) -- Dice roller - -**In-Person Gameplay:** -- Players use tablets/phones to access web character sheets -- DM uses web for campaign notes - -**Key Insight:** Tabletop RPG went digital - web is perfect for character management, rules lookup - ---- - -### Common Patterns Across Industry - -**Web = "Management Plane"** -- Account, billing, subscription -- Character planning and build theory -- Trading, market analysis, economics -- Community, news, forums -- Wiki, guides, knowledge base - -**Game = "Experience Plane"** -- Gameplay, combat, quests, story -- Real-time multiplayer and chat -- Immersive visuals, sound, animations -- Social features during gameplay - ---- - -## Recommended Implementation Phases - -### Phase 1: Essential Web Features (MVP) - -**Goal:** Fix technical debt, enable basic account/character management - -1. **Refactor public_web to use API** (Technical Debt) - - Replace stub service calls with HTTP requests to API - - Update auth helpers to validate sessions via API - - Remove stub service modules - - Test all existing views - -2. **Authentication Flows** - - User registration with email verification - - Login with session management - - Password reset flow - - Logout - -3. **Character Gallery** - - View all characters (read-only) - - Character detail pages - - Basic stats and equipment display - -4. **Account Settings** - - Change password (requires re-auth) - - Change email (with verification) - - View account info (registration date, tier) - -5. **Dev Blog / News Feed** - - Simple blog posts (markdown-based) - - Announcement system - - RSS feed - -**Deliverable:** Functional web frontend that complements game client - ---- - -### Phase 2: Monetization (Revenue) - -**Goal:** Enable subscription management and payment processing - -6. **Subscription Management** - - View current tier (Free, Basic, Premium, Elite) - - Upgrade/downgrade flows - - Stripe integration (Customer Portal) - - Subscription confirmation emails - -7. **Payment Processing** - - Stripe Checkout integration - - Webhook handling (subscription updates) - - Payment method management - -8. **Billing History** - - View past invoices - - Download receipts (PDF) - - Transaction log - -9. **Gift Code Redemption** - - Enter gift codes - - Apply promotional codes - - Track code usage - -**Deliverable:** Monetization system to support ongoing development - ---- - -### Phase 3: Community & Engagement - -**Goal:** Build community, increase retention - -10. **Marketplace (Web Version)** - - Browse listings (search, filter, sort, pagination) - - Place bids on auctions - - Create listings (auction or fixed price) - - My listings / My bids - - Transaction history - - Price analytics and charts - -11. **Leaderboards** - - Global rankings (level, wealth, achievements) - - Seasonal leaderboards - - Category leaderboards (PvP, crafting, questing) - - Player profile links - -12. **Session History Viewer** - - View past session logs (markdown export from API) - - Search sessions by date, characters, party members - - Share session links publicly (if enabled) - -13. **Player Profiles** - - Public character pages (if user enables) - - Achievement showcase - - Stats and analytics - - Session history - -**Deliverable:** Community features to keep players engaged - ---- - -### Phase 4: Advanced Features - -**Goal:** Expand platform, add convenience features - -14. **Guild Management Hub** - - Create/manage guilds - - Guild roster management - - Guild bank (shared resources) - - Guild event scheduling - -15. **Forums / Community** - - Discussion boards (or Discord/Reddit integration) - - Official announcements - - Player-to-player help - -16. **Analytics Dashboard** - - Account stats (playtime, characters, sessions) - - Character progress charts (XP, gold, level timeline) - - Combat analytics (win rate, damage dealt) - -17. **Support / Help Desk** - - Submit support tickets - - Track ticket status - - FAQ / knowledge base - - Bug report submission - -**Deliverable:** Mature platform with advanced features - ---- - -## Character Creation: Web vs Game Recommendation - -**Character creation wizard can exist in BOTH, but prioritize based on your goals:** - -### Option 1: Game Client Primary (Recommended) - -**Pros:** -- Better UX (3D character preview, animations, music) -- Immersive first-time experience -- Visual customization (face, hair, body type) -- Immediate transition to gameplay after creation - -**Cons:** -- Requires downloading game client before creating character -- Can't create characters on mobile (unless Godot exports to mobile) - -**When to choose:** If you want character creation to be part of the game experience - ---- - -### Option 2: Web Primary (Accessibility) - -**Pros:** -- Accessible from anywhere (phone, tablet, any browser) -- Can create characters before downloading game -- Faster load times (no 3D assets) -- Good for planning builds (skill tree preview) - -**Cons:** -- Less immersive (no 3D preview) -- Limited visual customization (no character model) -- Feels more administrative than experiential - -**When to choose:** If you want to reduce friction (create character on phone, play on desktop later) - ---- - -### Option 3: Both (Best of Both Worlds) - -**Implementation:** -- Web: "Quick Create" - Name, class, origin (minimal wizard) -- Game: "Full Create" - Visual customization, 3D preview, full immersion - -**When to choose:** If you want maximum flexibility - -**Recommendation:** Start with game-only (better UX), add web later if needed - ---- - -## Mobile Considerations - -### Public Web (Mobile-Responsive) - -The web frontend should be **fully mobile-responsive** for: -- Account management (on the go) -- Character viewing (check stats while away from PC) -- Marketplace browsing (trading from phone) -- News and community (read patch notes on commute) - -**Implementation:** -- Responsive CSS (mobile-first design) -- Touch-friendly UI (large buttons, swipe gestures) -- Progressive Web App (PWA) support (installable on phone) - -### Godot Client (Mobile Export - Future) - -Godot supports mobile export (iOS, Android), but: -- Requires significant UI/UX changes (touch controls) -- Performance considerations (mobile GPUs) -- App store submission process -- Monetization changes (Apple/Google take 30% cut) - -**Recommendation:** Start with desktop, add mobile export later if demand exists - ---- - -## API Design Considerations - -### Endpoint Organization - -**Authentication:** -- `POST /api/v1/auth/register` -- `POST /api/v1/auth/login` -- `POST /api/v1/auth/logout` -- `POST /api/v1/auth/forgot-password` -- `POST /api/v1/auth/reset-password` -- `POST /api/v1/auth/verify-email` - -**Account Management:** -- `GET /api/v1/account/profile` -- `PATCH /api/v1/account/profile` -- `POST /api/v1/account/change-password` -- `POST /api/v1/account/change-email` -- `DELETE /api/v1/account` - -**Subscription:** -- `GET /api/v1/subscription/status` -- `POST /api/v1/subscription/create-checkout` -- `POST /api/v1/subscription/create-portal-session` -- `POST /api/v1/subscription/webhook` (Stripe) - -**Marketplace:** -- `GET /api/v1/marketplace/listings` -- `GET /api/v1/marketplace/listings/:id` -- `POST /api/v1/marketplace/listings` -- `POST /api/v1/marketplace/listings/:id/bid` -- `POST /api/v1/marketplace/listings/:id/buyout` -- `DELETE /api/v1/marketplace/listings/:id` - -**Leaderboards:** -- `GET /api/v1/leaderboards/:category` -- `GET /api/v1/leaderboards/player/:user_id` - -**News:** -- `GET /api/v1/news` (public, no auth required) -- `GET /api/v1/news/:slug` - ---- - -## Technology Stack Summary - -### Public Web Frontend - -**Core:** -- Flask (web framework) -- Jinja2 (templating) -- HTMX (dynamic interactions) -- Vanilla CSS (styling) - -**Libraries:** -- Requests (HTTP client for API calls) -- Structlog (logging) -- Flask-WTF (CSRF protection) - -**Deployment:** -- Gunicorn (WSGI server) -- Nginx (reverse proxy) -- Docker (containerization) - -### Godot Game Client - -**Core:** -- Godot 4.5 (game engine) -- GDScript (scripting language) -- HTTP client (API calls) - -**Deployment:** -- Desktop exports (Windows, macOS, Linux) -- Web export (WebAssembly) - future -- Mobile exports (iOS, Android) - future - -### API Backend - -**Core:** -- Flask (REST API framework) -- Appwrite (database, auth, realtime) -- RQ + Redis (async task queue) -- Anthropic API (Claude AI for DM) - -**Libraries:** -- Dataclasses (data modeling) -- PyYAML (config, game data) -- Structlog (logging) -- Requests (external API calls) - ---- - -## Conclusion - -**Public Web Frontend:** -- **Purpose:** Account management, character planning, community engagement -- **Features:** Authentication, subscriptions, marketplace, news, leaderboards, analytics -- **Security:** Payment processing, password management, 2FA, audit logs -- **Accessibility:** Mobile-responsive, SEO-friendly, fast load times - -**Godot Game Client:** -- **Purpose:** Immersive gameplay experience -- **Features:** Combat, quests, story progression, real-time multiplayer, inventory -- **Experience:** 3D graphics, animations, sound design, music -- **Performance:** Real-time updates, WebSocket communication, optimized rendering - -**Both frontends:** -- Thin clients (no business logic) -- Make HTTP requests to API backend -- API validates everything (security, permissions, business rules) -- Microservices architecture (independent deployment) - -**Next Steps:** -1. Refactor public_web technical debt (remove stub services) -2. Implement Phase 1 web features (MVP) -3. Continue Godot client development (gameplay features) -4. Phase 2+ based on user feedback and revenue needs - ---- - -**Document Version:** 1.0 -**Last Updated:** November 17, 2025 -**Next Review:** After Phase 1 completion