Jocaru/echoes-of-the-ash
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
main
echoes-of-the-ash/docs/archive/PWA_IMPLEMENTATION.md
Joan 33cc9586c2 What a mess
2025-11-07 15:27:13 +01:00

8.0 KiB
Raw Permalink Blame History

PWA Implementation Summary

What Was Created

I've successfully set up a complete Progressive Web App (PWA) infrastructure for Echoes of the Ashes, deployable via Docker with Traefik reverse proxy at echoesoftheashgame.patacuack.net.

Project Structure Created

echoes_of_the_ashes/
├── pwa/                          # React PWA Frontend
│   ├── public/                   # Static assets (icons needed)
│   ├── src/
│   │   ├── components/
│   │   │   ├── Login.tsx         # Auth UI (login/register)
│   │   │   ├── Login.css
│   │   │   ├── Game.tsx          # Main game interface
│   │   │   └── Game.css
│   │   ├── contexts/
│   │   │   └── AuthContext.tsx   # Auth state management
│   │   ├── hooks/
│   │   │   └── useAuth.ts        # Custom auth hook
│   │   ├── services/
│   │   │   └── api.ts            # Axios API client
│   │   ├── App.tsx               # Main app + routing
│   │   ├── App.css
│   │   ├── main.tsx              # Entry point + SW registration
│   │   └── index.css
│   ├── vite.config.ts            # Vite + PWA plugin config
│   ├── tsconfig.json
│   ├── package.json
│   ├── .gitignore
│   └── README.md
│
├── api/                          # FastAPI Backend
│   ├── main.py                   # API routes + JWT auth
│   └── requirements.txt          # FastAPI, JWT, bcrypt
│
├── Dockerfile.pwa                # Multi-stage React build + Nginx
├── Dockerfile.api                # Python FastAPI container
├── nginx.conf                    # Nginx config with API proxy
├── migrate_web_auth.py           # Database migration script
├── docker-compose.yml            # Updated with PWA services
└── PWA_DEPLOYMENT.md             # Deployment guide

Features Implemented

✅ Progressive Web App Features

  • React 18 with TypeScript for type safety
  • Vite for fast builds and dev server
  • Service Worker with Workbox for offline support
  • Web App Manifest for install-to-homescreen
  • Mobile Responsive design with CSS3
  • Auto-update prompts when new version available

✅ Authentication System

  • JWT-based authentication (7-day tokens)
  • Bcrypt password hashing with salt
  • Register/Login endpoints
  • Separate from Telegram auth (can have both)
  • Database migration to support web users

✅ API Backend

  • FastAPI REST API
  • CORS configured for PWA domain
  • JWT verification middleware
  • Player state endpoint
  • Movement endpoint (placeholder)
  • Easy to extend with new endpoints

✅ Docker Deployment

  • Multi-stage build for optimized React bundle
  • Nginx serving static files + API proxy
  • Traefik labels for automatic HTTPS
  • SSL certificates via Let's Encrypt
  • Three services: DB, Bot, Map Editor, API, PWA

Architecture

Internet
   │
   ▼
Traefik (HTTPS)
   │
   ├─► echoesoftheash.patacuack.net → Map Editor (existing)
   └─► echoesoftheashgame.patacuack.net → PWA
            │
            ├─► / → React App (Nginx)
            └─► /api/* → FastAPI Backend
                          │
                          ▼
                     PostgreSQL

Technology Stack

Layer Technology
Frontend React 18, TypeScript, Vite
PWA Workbox, Service Workers, Web Manifest
Routing React Router 6
State React Context API (Zustand ready)
HTTP Axios with interceptors
Backend FastAPI, Uvicorn
Auth JWT (PyJWT), Bcrypt
Database PostgreSQL (existing)
Web Server Nginx
Container Docker multi-stage builds
Proxy Traefik with Let's Encrypt

Database Changes

Added columns to players table:

  • id - Serial auto-increment (for web users)
  • username - Unique username (nullable)
  • password_hash - Bcrypt hash (nullable)
  • telegram_id - Now nullable (was required)

Constraint: Either telegram_id OR username must be set.

API Endpoints

Authentication

  • POST /api/auth/register - Create account
  • POST /api/auth/login - Get JWT token
  • GET /api/auth/me - Get current user

Game

  • GET /api/game/state - Player state (health, stamina, location, etc.)
  • POST /api/game/move - Move player (placeholder)

Deployment Instructions

1. Run Migration

docker exec -it echoes_of_the_ashes_bot python migrate_web_auth.py

2. Add JWT Secret to .env

JWT_SECRET_KEY=your-super-secret-key-here

3. Build & Deploy

docker-compose up -d --build echoes_of_the_ashes_api echoes_of_the_ashes_pwa

4. Verify

# Check API
curl https://echoesoftheashgame.patacuack.net/api/

# Check PWA
curl https://echoesoftheashgame.patacuack.net/

What Still Needs Work

Critical

  1. Icons: Create actual PWA icons (currently placeholder README)

    • pwa-192x192.png
    • pwa-512x512.png
    • apple-touch-icon.png
    • favicon.ico

  2. NPM Install: Run npm install in pwa/ directory before building

  3. API Integration: Complete game state endpoints

    • Full inventory system
    • Combat actions
    • NPC interactions
    • Movement logic

Nice to Have

  1. Push Notifications: Web Push API implementation
  2. WebSockets: Real-time updates for multiplayer
  3. Offline Mode: Cache game data for offline play
  4. UI Polish: Better visuals, animations, sounds
  5. More Components: Inventory, Combat, Map, Profile screens

Key Files to Review

  1. pwa/src/App.tsx - Main app structure
  2. api/main.py - API endpoints and auth
  3. nginx.conf - Nginx configuration
  4. docker-compose.yml - Service definitions
  5. PWA_DEPLOYMENT.md - Full deployment guide

Security Considerations

✅ Implemented:

  • JWT tokens with expiration
  • Bcrypt password hashing
  • HTTPS only (Traefik redirect)
  • CORS restrictions
  • SQL injection protection (SQLAlchemy)

⚠️ Consider Adding:

  • Rate limiting on API endpoints
  • Refresh tokens
  • Account verification (email)
  • Password reset flow
  • Session management
  • Audit logging

Performance Optimizations

✅ Already Configured:

  • Nginx gzip compression
  • Static asset caching (1 year)
  • Service worker caching (API 1hr, images 30d)
  • Multi-stage Docker builds
  • React production build

Testing Checklist

Before going live:

  • Run migration script
  • Generate JWT secret key
  • Create PWA icons
  • Test registration flow
  • Test login flow
  • Test API authentication
  • Test on mobile device
  • Test PWA installation
  • Test service worker caching
  • Test HTTPS redirect
  • Test Traefik routing
  • Backup database
  • Monitor logs for errors

Next Steps

  1. Immediate (to deploy):

    cd pwa
npm install
cd ..
docker-compose up -d --build echoes_of_the_ashes_api echoes_of_the_ashes_pwa

  2. Short-term (basic functionality):

    • Implement real game state API
    • Create inventory UI
    • Add movement with map
    • Basic combat interface

  3. Medium-term (full features):

    • Push notifications
    • WebSocket real-time updates
    • Offline mode
    • Advanced UI components

  4. Long-term (polish):

    • Animations and transitions
    • Sound effects
    • Tutorial/onboarding
    • Achievements system

Documentation

All documentation created:

  • pwa/README.md - PWA project overview
  • PWA_DEPLOYMENT.md - Deployment guide
  • pwa/public/README.md - Icon requirements
  • This file - Implementation summary

Questions?

See PWA_DEPLOYMENT.md for:

  • Detailed deployment steps
  • Troubleshooting guide
  • Architecture diagrams
  • Security checklist
  • Monitoring setup
  • Backup procedures

Status: 🟡 Ready to Deploy (after npm install + icons)

Deployable: Yes, with basic auth and placeholder UI
Production Ready: Needs more work on game features
Documentation: Complete ✓

Reference in New Issue View Git Blame Copy Permalink