Platform Architecture: Web + iOS

Decision

PadawanForge uses a two-surface delivery model decided in v1.4.1:

SurfaceScope
Web (Cloudflare Workers)Demo experience + Admin dashboard
iOS Native AppFull game: training sessions, multiplayer, NPC chat, player progression

The backend APIs remain on Cloudflare Workers and are shared by both surfaces.

Rationale: The full game requires native device capabilities (offline play, push notifications, richer UI interactions) and benefits from App Store distribution. The web platform excels at low-friction anonymous demos and admin tooling that does not require installation.

Platform Responsibilities

Web (Cloudflare Workers)

RouteDescription
/demoAnonymous cognitive training showcase (no auth required)
/admin/*Content management dashboard (admin role required)
/api/*Shared REST + WebSocket backend (used by web and iOS)
/login, /documentationAuth and docs pages

Game pages (/game, /training, /catalog, /academy) remain in the codebase as API reference during iOS development but are not linked in main navigation.

iOS App (planned)

  • Full training game sessions (database-backed, offline-capable)
  • Multiplayer game rooms and real-time chat
  • NPC interactions and conversation history
  • Player profile, progression, achievements
  • Messages, catalog browsing, player directory

API Contract

The iOS app consumes existing Cloudflare Workers API endpoints:

Game Endpoints

POST /api/games/sessions          — Create training session
GET  /api/games/topics            — List game topics
GET  /api/games/challenges/:id    — Get next challenge for session
POST /api/games/answers           — Submit answer and update progress

Player Endpoints

GET  /api/players/:uuid           — Player profile
GET  /api/players/:uuid/stats     — Player statistics

Real-time Endpoints

WS   /api/lobby/:id/websocket     — Real-time multiplayer rooms

Auth Endpoints

GET  /api/auth/google             — Initiate Google OAuth
GET  /api/auth/discord            — Initiate Discord OAuth
GET  /api/auth/callback/*         — OAuth callbacks
POST /api/auth/logout             — Session termination

NPC Endpoints

GET  /api/npcs                    — List NPCs
POST /api/npcs/:id/chat           — Chat with NPC

Development Approach

  1. Web platform is stable — Demo and Admin are the only active web features.
  2. API-first — All game logic is exposed via REST/WebSocket APIs that the iOS app will consume.
  3. Shared database — iOS and web share the same Cloudflare D1 database and player records.
  4. Auth compatibility — OAuth flows work for both web sessions (cookies) and iOS (token-based).
← Database Schema Session Management & RBAC →
PadawanForge v1.4.2