927 lines
31 KiB
Markdown
927 lines
31 KiB
Markdown
# 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
|