# Quality App v2 - Quick Reference Guide

## 📂 Complete File Listing

### Python Application Files (~865 lines)

#### Core Application
- `app/__init__.py` (120 lines) - App factory, blueprint registration
- `app/config.py` (70 lines) - Configuration management
- `app/auth.py` (90 lines) - Authentication utilities
- `app/database.py` (100 lines) - Database connection pooling
- `app/routes.py` (70 lines) - Main routes (login, dashboard)

#### Modules
- `app/modules/quality/routes.py` (40 lines) - Quality module routes
- `app/modules/settings/routes.py` (50 lines) - Settings module routes
- `app/models/__init__.py` - Model package (expandable)

#### Entry Points
- `run.py` (20 lines) - Development server
- `wsgi.py` (10 lines) - Production WSGI entry
- `gunicorn.conf.py` (20 lines) - Gunicorn configuration
- `init_db.py` (150 lines) - Database initialization

### HTML Templates (~1200 lines)

#### Base Templates
- `app/templates/base.html` (110 lines) - Main layout template
- `app/templates/login.html` (40 lines) - Login page

#### Main Pages
- `app/templates/dashboard.html` (90 lines) - Dashboard with modules
- `app/templates/profile.html` (60 lines) - User profile

#### Error Pages
- `app/templates/errors/404.html` (20 lines) - Page not found
- `app/templates/errors/500.html` (20 lines) - Server error
- `app/templates/errors/403.html` (20 lines) - Access forbidden

#### Quality Module Templates
- `app/templates/modules/quality/index.html` (60 lines)
- `app/templates/modules/quality/inspections.html` (80 lines)
- `app/templates/modules/quality/reports.html` (70 lines)

#### Settings Module Templates
- `app/templates/modules/settings/index.html` (50 lines)
- `app/templates/modules/settings/general.html` (60 lines)
- `app/templates/modules/settings/users.html` (80 lines)
- `app/templates/modules/settings/database.html` (60 lines)

### Stylesheets (~600 lines)

- `app/static/css/base.css` (400 lines) - Global styles, responsive design
- `app/static/css/login.css` (200 lines) - Login page styling

### JavaScript (~150 lines)

- `app/static/js/base.js` (150 lines) - Utilities, Bootstrap init, theme toggle

### Docker & Deployment

- `Dockerfile` - Python 3.11 slim, production optimized
- `docker-compose.yml` - MariaDB + Flask services
- `docker-entrypoint.sh` - Container startup script
- `.dockerignore` - Docker build optimization

### Configuration & Documentation

- `requirements.txt` - Python dependencies
- `.env.example` - Environment variables template
- `.gitignore` - Git ignore rules
- `README.md` - Deployment and setup guide
- `ARCHITECTURE.md` - Technical architecture guide
- `PROJECT_SUMMARY.md` - Project overview
- `QUICK_REFERENCE.md` - This file

---

## 🚀 Quick Commands

### Deployment
```bash
# One-command deploy
./quick-deploy.sh

# Manual deployment
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f app
```

### Database
```bash
# Initialize database
docker-compose exec app python init_db.py

# Backup database
docker-compose exec mariadb mariadb-dump -u quality_user -p quality_db > backup.sql

# Access MariaDB CLI
docker-compose exec mariadb mariadb -u quality_user -p
```

### Development
```bash
# Local setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python init_db.py
python run.py
```

---

## 🔐 Default Credentials

**CHANGE IMMEDIATELY AFTER FIRST LOGIN!**

- Username: `admin`
- Password: `admin123`

---

## 📱 Access Points

- **Application**: `http://localhost:8080`
- **Database**: `localhost:3306` (MariaDB)
- **User**: `quality_user`

---

## 📋 Module Features

### Quality Module
✅ Inspection management
✅ Quality reports
✅ Status tracking
✅ Notes and comments

### Settings Module
✅ General settings
✅ User management
✅ Database configuration
✅ Application preferences

---

## 🗄️ Database Tables

1. **users** - User accounts
   - Fields: id, username, email, full_name, role, is_active, timestamps

2. **user_credentials** - Password management
   - Fields: id, user_id, password_hash, timestamps

3. **quality_inspections** - Quality records
   - Fields: id, type, status, inspector_id, date, notes, timestamps

4. **application_settings** - Configuration
   - Fields: id, key, value, type, timestamps

---

## 🔧 Environment Variables

```ini
# Flask
FLASK_ENV=production
FLASK_DEBUG=False
SECRET_KEY=your-secret-key

# Database
DB_HOST=mariadb
DB_PORT=3306
DB_USER=quality_user
DB_PASSWORD=your-password
DB_NAME=quality_db

# Application
APP_PORT=8080
APP_HOST=0.0.0.0
LOG_LEVEL=INFO
```

---

## 📊 Application Structure

```
Request
  ↓
Authentication Check
  ↓
Route Handler (Flask Blueprint)
  ↓
Business Logic (auth.py)
  ↓
Database Query (database.py)
  ↓
Template Rendering
  ↓
Response (HTML/JSON)
```

---

## 🛡️ Security Features

- ✅ Password hashing (SHA256)
- ✅ Session management
- ✅ SQL injection prevention
- ✅ CSRF protection
- ✅ Connection pooling
- ✅ Error handling

---

## 📈 Performance

- Connection pooling: 10 connections
- Worker processes: CPU count × 2 + 1
- Worker timeout: 60 seconds
- Max content length: 100MB

---

## 📚 Documentation Files

1. **README.md** - Deployment, setup, troubleshooting
2. **ARCHITECTURE.md** - Technical deep dive, patterns, scalability
3. **PROJECT_SUMMARY.md** - Overview, features, statistics
4. **QUICK_REFERENCE.md** - This file

---

## ⚡ Performance Tips

1. Use Docker for consistent deployments
2. Keep database indexes optimized
3. Monitor logs for errors
4. Regular backups of data
5. Update Python dependencies regularly

---

## 🔄 Workflow

### Development
1. Make code changes
2. Test locally with `python run.py`
3. Check database migrations
4. Verify Docker build

### Staging
1. Build Docker image
2. Run `docker-compose up`
3. Test all features
4. Check performance

### Production
1. Update .env with production values
2. Run `./quick-deploy.sh`
3. Verify health checks
4. Monitor logs
5. Regular backups

---

## 🐛 Troubleshooting

| Issue | Solution |
|-------|----------|
| DB connection failed | Check if mariadb service is running: `docker-compose ps` |
| Port already in use | Change APP_PORT in .env and restart |
| Template not found | Verify file path in `app/templates/` |
| Import error | Install requirements: `pip install -r requirements.txt` |
| Database empty | Run: `docker-compose exec app python init_db.py` |

---

## 🎯 Next Features to Add

- [ ] Advanced search and filtering
- [ ] Data export (Excel/PDF)
- [ ] Email notifications
- [ ] API endpoints
- [ ] User activity logging
- [ ] Two-factor authentication
- [ ] Dashboard customization
- [ ] Batch operations
- [ ] Data validation rules
- [ ] Audit trail

---

## 📞 Support

- Flask docs: https://flask.palletsprojects.com/
- MariaDB docs: https://mariadb.com/kb/
- Docker docs: https://docs.docker.com/

---

## 📝 Notes

- Database initializes automatically on first run
- Logs are rotated (10 files × 10MB)
- All timestamps in UTC
- UTF-8 support for international characters
- Production-ready with Gunicorn

---

**Quality App v2** - Built for Scale, Designed for Extension