v_1

README.md

@@ -0,0 +1,68 @@
+# Mobile Contract Manager
+
+A full-stack web application for managing mobile contracts with role-based access control, MFA support, and a modern UI.
+
+## Features
+
+- **Authentication**: JWT-based with MFA (Google Authenticator / TOTP)
+- **Roles**: Admin (full access) and User (read-only)
+- **MFA**: QR code setup via Google Authenticator
+- **First Login**: Forces password change on first login
+- **Database**: PostgreSQL (self-hosted)
+- **Frontend**: React + Tailwind CSS (dark modern UI)
+
+## Default Credentials
+
+| Username | Password | Role  |
+|----------|----------|-------|
+| admin    | admin    | Admin |
+
+> You will be prompted to change the password on first login.
+
+## Quick Start
+
+1. **Clone / extract** this project
+
+2. **Configure** `.env` (change passwords and secrets for production!):
+   ```
+   POSTGRES_PASSWORD=your_secure_password
+   JWT_SECRET=your_super_secret_key_min_32_characters
+   JWT_REFRESH_SECRET=another_super_secret_key_min_32_chars
+   ENCRYPTION_KEY=exactly32characterslongkeyhere123
+   ```
+
+3. **Deploy** with Docker Compose:
+   ```bash
+   docker compose up -d
+   ```
+
+4. **Access** the app at `http://localhost` (or port defined in APP_PORT)
+
+## Stopping the App
+
+```bash
+docker compose down
+```
+
+To also remove the database volume (all data):
+```bash
+docker compose down -v
+```
+
+## Project Structure
+
+```
+├── backend/          # Node.js/Express API
+├── frontend/         # React SPA
+├── nginx/            # Reverse proxy config
+├── db-init/          # Database initialization SQL
+├── docker-compose.yml
+└── .env
+```
+
+## Security Notes
+
+- Change all `.env` secrets before production deployment
+- The `ENCRYPTION_KEY` must be exactly 32 characters
+- Consider using HTTPS (put a TLS-terminating reverse proxy in front)
+- Passwords are hashed with bcrypt (cost factor 12)