Login Sample App

A full-stack web application with secure user authentication, built with modern technologies and best practices.

🚀 Quick Start

Choose your preferred setup method:

Option 1: OS-Optimized Setup (Recommended)

• 🪟 Windows: .\start-windows.bat
• 🐧 Linux: ./start-linux.sh
• 🍎 macOS: ./start-macos.sh

Option 2: Auto-Detection

• Windows: .\start-auto.bat
• Unix-like: ./start-auto.sh

Option 3: Cross-Platform Default

docker-compose up --build

Expected Results:

• ✅ Frontend: http://localhost:3000
• ✅ Backend API: http://localhost:8000
• ✅ API Docs: http://localhost:8000/docs

📋 For detailed Docker setup and troubleshooting, see DOCKER_SETUP.md

🚀 Features

• User Authentication: Registration, login, logout with JWT tokens
• Secure Backend: FastAPI with PostgreSQL database
• Modern Frontend: React with Vite and Tailwind CSS
• Protected Routes: Dashboard accessible only to authenticated users
• Profile Management: View and edit user profiles
• Responsive Design: Beautiful UI that works on all devices
• Real-time Validation: Form validation with error handling
• Token Management: Automatic token refresh and secure logout

🛠️ Tech Stack

Backend

• Framework: FastAPI (Python)
• Database: PostgreSQL with SQLAlchemy ORM
• Authentication: JWT (JSON Web Tokens)
• Password Security: bcrypt hashing
• Migrations: Alembic
• Validation: Pydantic schemas

Frontend

• Framework: React 18
• Build Tool: Vite
• Styling: Tailwind CSS
• Routing: React Router v6
• HTTP Client: Axios
• Forms: React Hook Form
• Notifications: React Hot Toast
• Icons: Heroicons

📁 Project Structure

LoginSampleApp/
├── backend/                 # FastAPI backend application
│   ├── app/                # Application source code
│   │   ├── auth/           # Authentication utilities
│   │   ├── models/         # Database models
│   │   ├── routes/         # API route handlers
│   │   ├── schemas/        # Pydantic validation schemas
│   │   └── middleware/     # Custom middleware
│   ├── alembic/            # Database migrations
│   ├── requirements.txt    # Python dependencies
│   ├── .env.example       # Environment variables template
│   └── start.sh           # Backend startup script
├── frontend/               # React frontend application
│   ├── src/               # Application source code
│   │   ├── components/    # Reusable UI components
│   │   ├── pages/         # Page components
│   │   ├── context/       # React context providers
│   │   ├── services/      # API service layer
│   │   ├── hooks/         # Custom React hooks
│   │   └── utils/         # Utility functions
│   ├── package.json       # Node.js dependencies
│   ├── .env.example      # Environment variables template
│   └── start.sh          # Frontend startup script
├── docs/                  # Documentation
├── .gitignore            # Git ignore rules
└── README.md            # This file

🚦 Quick Start

🐳 Docker Setup (Recommended for BOOTCAMP)

One-command setup - No local dependencies required!

# Clone repository
git clone https://github.com/AmzurATG/LoginSampleApp.git
cd LoginSampleApp

# Start entire application with Docker
./start.sh

Access the application:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

See DOCKER_GUIDE.md for detailed Docker instructions.

---

🔧 Manual Setup (Alternative)

For developers who want to run without Docker:

Prerequisites

Option 1: Docker (Recommended)

• Docker and Docker Compose
• Git for version control

Option 2: Local Development

• Python 3.8+ for backend
• Node.js 16+ for frontend
• PostgreSQL database (if not using Docker)
• Git for version control

1. Clone the Repository

git clone <your-repository-url>
cd LoginSampleApp

🐳 Docker Setup (Recommended)

Docker provides the easiest way to run the complete application stack. All dependencies, database, and services are automatically configured.

Prerequisites

• Docker Desktop (Windows/macOS) or Docker + Docker Compose (Linux)
• Git for cloning the repository

Quick Start

# Clone the repository
git clone <repository-url>
cd LoginSampleApp

# Choose your preferred method:
.\start-windows.bat    # Windows
./start-linux.sh       # Linux  
./start-macos.sh       # macOS
./start-auto.sh        # Auto-detection (Unix)
.\start-auto.bat       # Auto-detection (Windows)

Access Points:

• 🌐 Frontend: http://localhost:3000
• 🔧 Backend API: http://localhost:8000
• 📚 API Docs: http://localhost:8000/docs

📋 For detailed Docker setup, troubleshooting, and advanced configurations, see docker-setup/DOCKER_SETUP.md

Docker Management & Cleanup

Quick Stop/Start

# Stop all services
docker-compose -f docker-setup/windows/docker-compose.windows.yml down  # Windows
docker-compose -f docker-setup/linux/docker-compose.linux.yml down     # Linux
docker-compose -f docker-setup/macos/docker-compose.macos.yml down     # macOS

# Restart services
.\start-windows.bat  # Windows
./start-linux.sh     # Linux
./start-macos.sh     # macOS

Complete Cleanup (⚠️ Removes all data)

# Windows
docker-compose -f docker-setup/windows/docker-compose.windows.yml down
docker rmi windows-backend:latest windows-frontend:latest postgres:15
docker volume rm windows_postgres_data
docker system prune -f

# Linux/macOS
docker-compose down
docker rmi linux-backend:latest linux-frontend:latest postgres:15  # or macos-*
docker volume rm linux_postgres_data  # or macos_postgres_data
docker system prune -f

📋 For complete cleanup instructions and troubleshooting, see docker-setup/DOCKER_SETUP.md

💻 Local Development Setup

2. Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Setup environment variables
cp .env.example .env
# Edit .env with your database credentials

# Setup database
./setup_db.sh

# Start backend server
./start.sh

The backend will be available at:

• API: http://localhost:8000
• API Docs: http://localhost:8000/docs

3. Frontend Setup

cd frontend

# Install dependencies
npm install

# Setup environment variables
cp .env.example .env
# Edit .env if needed (default should work)

# Start development server
npm run dev

The frontend will be available at: http://localhost:5173

📖 Usage

1. Access the Application: Open http://localhost:5173 in your browser
2. Register: Create a new account with email and password
3. Login: Sign in with your credentials
4. Dashboard: Access your profile and account settings
5. Profile Management: Update your personal information
6. Logout: Securely sign out of your account

🔒 Security Features

• Password Hashing: bcrypt with salt for secure password storage
• JWT Authentication: Stateless token-based authentication
• Token Expiration: Automatic token refresh and logout
• Input Validation: Comprehensive validation on both frontend and backend
• CORS Protection: Configured allowed origins
• SQL Injection Protection: SQLAlchemy ORM with parameterized queries
• Secure Headers: HTTP security headers implemented

🧪 Testing

Backend Testing

cd backend
python test_api.py

Frontend Testing

cd frontend
npm run test  # If tests are implemented

Manual Testing

• Visit http://localhost:8000/docs for interactive API documentation
• Use the frontend application for end-to-end testing

🐳 Docker Support

BOOTCAMP Quick Start

git clone https://github.com/AmzurATG/LoginSampleApp.git
cd LoginSampleApp
./start.sh

Manual Docker Commands

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

What's Included

• ✅ Frontend: React app with Nginx (Port 3000)
• ✅ Backend: FastAPI with auto-migrations (Port 8000)
• ✅ Database: PostgreSQL with persistent storage (Port 5432)
• ✅ Health Checks: Automatic service monitoring
• ✅ One Command Setup: No local dependencies needed

See DOCKER_GUIDE.md for comprehensive Docker documentation.

🌐 Production Deployment

Environment Variables

For Docker (.env):

# Database
POSTGRES_PASSWORD=postgres

# Backend
SECRET_KEY=your-super-secret-key-change-this-in-production-make-it-very-long-and-random
ENVIRONMENT=development

# Frontend
VITE_API_BASE_URL=http://localhost:8000

# CORS
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173,http://localhost:80

Backend (.env) (for local development):

DATABASE_URL=postgresql://user:password@host:port/database
SECRET_KEY=your-production-secret-key-min-32-characters
ENVIRONMENT=production
ALLOWED_ORIGINS=https://yourdomain.com

Frontend (.env) (for local development):

VITE_API_BASE_URL=https://api.yourdomain.com

Security Checklist

• Change default secret keys
• Use HTTPS in production
• Configure proper CORS origins
• Set up database connection pooling
• Implement rate limiting
• Set up monitoring and logging
• Use non-root users in Docker containers
• Keep Docker images updated
• Scan Docker images for vulnerabilities
• Enable database backups
• Configure firewall rules

📚 API Documentation

Authentication Endpoints

• POST /api/auth/register - Register new user
• POST /api/auth/login - User login
• POST /api/auth/refresh - Refresh access token

User Endpoints

• GET /api/users/me - Get current user profile
• PUT /api/users/me - Update user profile
• DELETE /api/users/me - Deactivate user account

System Endpoints

• GET / - Root endpoint with API info
• GET /health - Health check endpoint

For detailed API documentation, visit http://localhost:8000/docs when the backend is running.

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and commit: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Guidelines

• Follow PEP 8 for Python code
• Use ESLint and Prettier for JavaScript/React code
• Write tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PR

🛠️ Development Tools

Backend Tools

• FastAPI: Web framework
• SQLAlchemy: ORM
• Alembic: Database migrations
• Pydantic: Data validation
• bcrypt: Password hashing
• PyJWT: JSON Web Tokens

Frontend Tools

• Vite: Build tool and dev server
• React: UI library
• React Router: Client-side routing
• Tailwind CSS: Utility-first CSS framework
• Axios: HTTP client
• React Hook Form: Form handling
• React Hot Toast: Notifications

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

If you encounter any issues or have questions:

1. Check the documentation
2. Look through existing issues
3. Create a new issue with detailed information
4. For urgent matters, contact the development team

🎯 Roadmap

• Email verification system
• Password reset functionality
• Two-factor authentication (2FA)
• User roles and permissions
• Social media login integration
• Mobile app version
• Advanced user analytics
• API rate limiting
• Comprehensive test suite
• CI/CD pipeline

📊 Status

✅ Backend: Fully implemented and tested ✅ Frontend: Fully implemented and tested
✅ Authentication: JWT-based security working ✅ Database: PostgreSQL integration complete ✅ Documentation: Comprehensive docs available ✅ Docker: Container support ready

---

Built with ❤️ by the development team