planning and docs update
This commit is contained in:
@@ -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
|
||||
Reference in New Issue
Block a user