echoes-of-the-ash/pwa

Echoes of the Ashes - PWA

A Progressive Web App (PWA) version of Echoes of the Ashes, bringing the post-apocalyptic survival RPG to web and mobile browsers.

Features

• 🎮 Play on Any Device: Works on desktop, tablet, and mobile browsers
• 📱 Install as App: Add to home screen for app-like experience
• 🔔 Push Notifications: Get notified of game events even when app is closed
• 📶 Offline Support: Continue playing even without internet connection (coming soon)
• 🔐 Web Authentication: Separate login system from Telegram
• ⚡ Fast & Responsive: Optimized for quick loading and smooth gameplay

Technology Stack

• Frontend: React 18 + TypeScript + Vite
• Styling: CSS3 with mobile-first responsive design
• PWA: Workbox for service worker and offline functionality
• API: FastAPI backend with JWT authentication
• State Management: Zustand (lightweight alternative to Redux)
• HTTP Client: Axios with interceptors

Project Structure

pwa/
├── public/              # Static assets (icons, manifest)
├── src/
│   ├── components/      # React components
│   │   ├── Login.tsx    # Login/Register page
│   │   └── Game.tsx     # Main game interface
│   ├── contexts/        # React contexts
│   │   └── AuthContext.tsx  # Authentication state
│   ├── hooks/           # Custom React hooks
│   │   └── useAuth.ts   # Auth hook
│   ├── services/        # API services
│   │   └── api.ts       # Axios instance
│   ├── App.tsx          # Main app component
│   ├── App.css          # Global styles
│   ├── main.tsx         # Entry point
│   └── index.css        # Base styles
├── index.html           # HTML template
├── vite.config.ts       # Vite configuration + PWA setup
├── package.json         # Dependencies
└── tsconfig.json        # TypeScript configuration

Development

Prerequisites

• Node.js 20+
• npm or yarn

Install Dependencies

cd pwa
npm install

Run Development Server

npm run dev

The app will be available at http://localhost:3000

Build for Production

npm run build

Output will be in dist/ directory.

Deployment

The PWA is deployed as a Docker container behind Traefik reverse proxy:

• Production URL: https://echoesoftheashgame.patacuack.net
• SSL: Automatic HTTPS via Traefik + Let's Encrypt
• Container: Nginx serving static React build

Docker Build

docker build -f Dockerfile.pwa -t echoes-pwa .

Environment Variables

No environment variables needed for the PWA frontend. API URL is determined by import.meta.env.PROD:

• Development: http://localhost:3000 (proxied to API)
• Production: https://echoesoftheashgame.patacuack.net

API Integration

The PWA communicates with the FastAPI backend at /api/*:

Authentication Endpoints

• POST /api/auth/register - Register new account
• POST /api/auth/login - Login with credentials
• GET /api/auth/me - Get current user info

Game Endpoints

• GET /api/game/state - Get player state
• POST /api/game/move - Move player
• More endpoints coming soon...

PWA Features

Service Worker

Configured in vite.config.ts using vite-plugin-pwa:

• Auto Update: Prompts user to reload when new version available
• Cache Strategy: NetworkFirst for API, CacheFirst for images
• Offline Ready: Caches essential assets for offline use

Manifest

PWA manifest in vite.config.ts:

• Name: Echoes of the Ashes
• Icons: 192x192 and 512x512 PNG icons
• Display: Standalone (looks like native app)
• Theme: Dark mode (#1a1a1a)

Installation

Users can install the PWA:

• Desktop: Click install button in address bar
• iOS: Share → Add to Home Screen
• Android: Browser will prompt to install

Roadmap

• Complete game state API integration
• Implement inventory management UI
• Add combat interface
• Create interactive map view
• Implement NPC interactions
• Add push notification service
• Improve offline caching strategy
• Add service worker update notifications
• Implement WebSocket for real-time updates
• Add sound effects and music
• Create onboarding tutorial
• Add accessibility features

Contributing

This is part of the Echoes of the Ashes project. See main README for contribution guidelines.

License

Same as main project.