# 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