# 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

```bash
cd pwa
npm install
```

### Run Development Server

```bash
npm run dev
```

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

### Build for Production

```bash
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

```bash
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.