Flask MVC Application

A modern Flask web application built with MVC (Model-View-Controller) architecture, featuring TailwindCSS for styling and Alpine.js for interactive frontend functionality.

Features

• MVC Architecture: Clean separation of concerns with Models, Views, Controllers, and Services
• Flask Blueprints: Modular application structure with organized route handling
• SQLAlchemy ORM: Database abstraction with relationship management
• TailwindCSS: Utility-first CSS framework for rapid UI development
• Alpine.js: Lightweight JavaScript framework for reactive components
• User Authentication: Complete user registration, login, and profile management
• RESTful API: JSON API endpoints for external integrations
• Responsive Design: Mobile-first responsive design patterns
• Form Validation: Client-side and server-side form validation
• Flash Messages: User feedback system with notifications

Project Structure

py_roadmap/
├── app/
│   ├── __init__.py              # Application factory
│   ├── controllers/             # Route handlers (Controllers)
│   │   ├── __init__.py
│   │   ├── main_controller.py   # Main application routes
│   │   ├── auth_controller.py   # Authentication routes
│   │   └── api_controller.py    # API endpoints
│   ├── models/                  # Database models
│   │   ├── __init__.py
│   │   ├── base_model.py        # Base model with common fields
│   │   ├── user.py             # User model
│   │   └── post.py             # Post model (example)
│   ├── services/                # Business logic layer
│   │   ├── __init__.py
│   │   ├── main_service.py      # Main application logic
│   │   ├── auth_service.py      # Authentication logic
│   │   └── api_service.py       # API logic
│   ├── templates/               # HTML templates (Views)
│   │   ├── base.html           # Base template
│   │   ├── main/               # Main page templates
│   │   └── auth/               # Authentication templates
│   └── static/                  # Static assets
│       ├── css/                # Stylesheets
│       ├── js/                 # JavaScript files
│       └── images/             # Image assets
├── config/
│   └── settings.py             # Application configuration
├── run.py                      # Application entry point
├── pyproject.toml             # Python dependencies
├── package.json               # Node.js dependencies (for TailwindCSS)
├── tailwind.config.js         # TailwindCSS configuration
└── README.md                  # This file

Installation

Prerequisites

• Python 3.11+
• Node.js 16+ (for TailwindCSS)
• Git

1. Clone the Repository

git clone <your-repository-url>
cd py_roadmap

2. Create Virtual Environment

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

3. Install Python Dependencies

pip install -e .

4. Install Node.js Dependencies

npm install

5. Environment Configuration

cp .env.example .env
# Edit .env file with your configuration

6. Build TailwindCSS

npm run build-css

7. Initialize Database

python -c "from app import create_app, db; app = create_app(); app.app_context().push(); db.create_all()"

Running the Application

Development Mode

1. Start TailwindCSS build process (in one terminal):

npm run dev

2. Start Flask development server (in another terminal):

python run.py

The application will be available at http://localhost:5000

Production Mode

1. Build production assets:

npm run build

2. Set environment variables:

export FLASK_ENV=production
export SECRET_KEY=your-production-secret-key

3. Run with a production WSGI server:

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:8000 run:app

API Endpoints

Health Check

• GET /api/health - API health check

Users

• GET /api/users - Get all users
• GET /api/users/<id> - Get specific user
• POST /api/users - Create new user

Example API usage:

# Health check
curl http://localhost:5000/api/health

# Get all users
curl http://localhost:5000/api/users

# Create new user
curl -X POST http://localhost:5000/api/users \
  -H "Content-Type: application/json" \
  -d '{"username": "john", "email": "[email protected]", "password": "password123"}'

Development

Code Style

This project uses Black for code formatting and Flake8 for linting:

# Format code
black .

# Lint code
flake8 .

# Type checking
mypy .

Testing

Run tests with pytest:

pytest

Database Migrations

For database schema changes, you can use Flask-Migrate (add it to dependencies if needed):

pip install Flask-Migrate

Adding New Features

1. Controllers: Add new routes in app/controllers/
2. Models: Add new database models in app/models/
3. Services: Add business logic in app/services/
4. Templates: Add HTML templates in app/templates/
5. Static Assets: Add CSS/JS/images in app/static/

Technologies Used

Backend

• Flask: Lightweight WSGI web application framework
• SQLAlchemy: SQL toolkit and Object-Relational Mapping library
• Werkzeug: WSGI utility library for Python

Frontend

• TailwindCSS: Utility-first CSS framework
• Alpine.js: Minimal framework for composing JavaScript behavior
• Jinja2: Modern and designer-friendly templating language

Development Tools

• Black: Code formatter
• Flake8: Linting tool
• MyPy: Static type checker
• Pytest: Testing framework

Contributing

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

License

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

Support

If you have any questions or need help, please open an issue on GitHub.

Demo Credentials

For testing the application, you can use these demo credentials:

• Email: [email protected]
• Password: demo123

(Note: You'll need to create this user manually or add a seed script)