FastAPI HTMX

Web App providing boilerplate implementation for user management, roles, groups, and CRUD operations using HTMX, FastAPI and AlpineJS for rapid prototyping and without worrying for the user management.

External Libraries Used

This project leverages several external libraries to provide a robust and efficient solution. Below is a brief description of each library along with a link to their documentation:

FastAPI (v0.112.1): A modern, fast (high-performance), web framework for building APIs and serving HTML templates with Python 3.6+ based on standard Python type hints.
SQLAlchemy (v2.0.36): The Python SQL toolkit and Object Relational Mapper that gives application developers the full power and flexibility of SQL.
FastAPI Users (v13.0.0): Ready-to-use and customizable users management for FastAPI.
Uvicorn (v0.23.2): A lightning-fast ASGI server implementation, using uvloop and httptools.
Jinja2 (v3.1.4): A modern and designer-friendly templating language for Python.
NH3 (v0.2.18): A Python binding to the HTML sanitizer h3.
Alembic (v1.14.0): A lightweight database migration tool for usage with the SQLAlchemy Database Toolkit.
AlpineJS (loaded from CDN): A rugged, minimal framework for composing JavaScript behavior in your HTML templates.
Flowbite (loaded from CDN): A component library built on top of Tailwind CSS for building modern web interfaces.
Pydantic (v2.10.0): Data validation and settings management using Python type annotations.

Features Implemented

User Authentication and Authorization
Role Management
Group Management
Dashboard for managing users, roles, and groups
RESTful API endpoints for CRUD operations
HTML templates for the web interface
Database migrations with Alembic
Unified error handling approach.

To-Do (Future Enhancements)

🎨 Implement Theming using Flowbite and Tailwind
🚦 Implement a rate limiter to prevent abuse and ensure fair usage
✅ 📦 Integrate MinIO object storage for efficient file saving and management [Completed]
🔑 Add functionality to allow users to update their passwords
🔄 Implement a password reset feature on the login page
⚡ Implement rendering of blocks using FastAPI Fragment instead of reloading complete page or partials [In Progress]
📝 Develop a logging service to track and analyze user activity
✅ 🛡️ Implement CSRF protection to enhance security [Completed]
💾 Integrate Neon database (SQLite) for production use [In Progress]
✅ 🎨 Replace HyperScript code with Alpine JS [Completed]
🚀 Upgrading the boilerplate code to work with Python 12 and HTMX 2 [In Progress]
✅ 📱 Fixing the GUI issues appearing in mobile view [Completed]
🧪 Add more tests
🔧 Wrapper to handle the pydantic models inputs efficiently from front end

Demo

Admin Login Credential

email: superuser@admin.com
password: password123

Setting Up the Project

Creating the `.env` File

Create a .env file in the root directory of the project and add the following environment variables:

# Database Configuration
DATABASE_URL="sqlite+aiosqlite:///./users.db"
SECRET_KEY="super-secret-key-example-123456789"

# MinIO Configuration (Required for file uploads)
MINIO_URL="http://localhost:9000"
MINIO_ACCESS_KEY="minioadmin123456789"
MINIO_SECRET_KEY="miniosecret987654321xyz"
MINIO_BUCKET="my-fastapi-bucket"
MINIO_SECURE=false

# CSRF Protection
CSRF_SECRET_KEY="csrf-secret-key-example-987654321"
COOKIE_SAMESITE="lax"
COOKIE_SECURE=true

Replace your_secret_key with a strong secret key for your application.

Note: While using sample MinIO credentials will allow the database to record file uploads, the actual files won't be stored without valid MinIO server credentials. For full file storage functionality, set up a MinIO server or use valid MinIO service credentials.

Running the Project

Clone the repository:

git clone https://github.com/yourusername/project-management.git
cd project-management

Install dependencies: If you are using poetry, run:
```
poetry install
```
If you are using pip, run:
```
pip install -r requirements.txt
```
Run database migrations:
```
alembic upgrade head
```

Run database migrations:

alembic revision --autogenerate -m "Initial migration"

Insert Required import in Migration File:

After generating the initial migration, open the newly created revision file in app/migrations/versions/ and add the following imports at the top of the file:
```
import fastapi_users_db_sqlalchemy.generics
import app.models.groups
```
Apply the changes:
```
alembic upgrade head
```
Start the application: If you are using poetry, run:
```
poetry run uvicorn main:app --reload
```
If you are using uvicorn directly, run:
```
uvicorn main:app --reload
```
Access the application: Open your web browser and navigate to http://127.0.0.1:8000.

Updating Model References in `init_models`

When you define a new Database model in your application, it's essential to update the init_models function to ensure that Alembic can detect and generate migrations for this new model correctly. This step is crucial for maintaining the integrity of your database schema and ensuring that all models are correctly versioned.

Steps to Update `init_models`

Locate init_models Function: Open the base.py file in app/database/base.py. This file contains the init_models function, which is responsible for importing all the models in your application.
Add New Model Import: Once you have defined a new model in your application, you need to import it in the init_models function. Ensure that you follow the existing import structure. For example, if your new model is Invoice and it's located in the models.financial module, you would add the following line:
```
from ..models.financial import Invoice  # noqa: F401
```
The # noqa: F401 comment at the end of the import statement tells the linter to ignore the "imported but unused" warning, as the import is necessary for Alembic to detect and generate migrations for the model.
Follow Import Conventions: If you have multiple models in the same module, you can import them in a single line to keep the init_models function organized. For example:
```
from ..models.financial import Invoice, Payment, Transaction  # noqa: F401
```
Save Changes: After adding the import statement for your new model, save the changes to the base.py file.
Generate Alembic Migration: With the new model imported in the init_models function, you can now generate an Alembic migration script that includes this model. Run the Alembic command to autogenerate a migration:
```
alembic revision --autogenerate -m "Added new model Invoice"
```
Review and Apply Migration: Always review the generated migration script to ensure it accurately represents the changes to your models. After reviewing, apply the migration to update your database schema:
```
alembic upgrade head
```

Project Structure

Below is an overview of the project structure for application. This structure is designed to organize the application's components logically, making it easier to navigate and maintain.

FastAPI-HTMX/
├── app/
│ ├── core/             # Core application logic and utilities
│ │ ├── config.py         # Application configuration
│ │ └── security.py       # Security utilities
│ ├── database/         # Database configurations and connections
│ │ ├── base.py           # Base database setup
│ │ └── session.py        # Database session management
│ ├── migrations/         # Alembic migration scripts
│ ├── models/           # SQLAlchemy ORM models
│ │ ├── groups.py         # Group model definitions
│ │ ├── roles.py          # Role model definitions
│ │ └── users.py          # User model definitions
│ ├── routes/           # API route definitions
│ │ ├── api/
│ │ │ ├── auth.py         # Authentication endpoints
│ │ │ └── users.py        # User management endpoints
│ │ └── view/           # View routes for web interface
│ │   ├── group.py        # Group management views
│ │   ├── role.py         # Role management views
│ │   └── view_crud.py    # SQLAlchemyCRUD class
│ ├── schema/           # Pydantic schemas
│ │ ├── group.py          # Group schemas
│ │ ├── role.py           # Role schemas
│ │ └── user.py           # User schemas
│ ├── static/           # Static files
│ │ ├── css/              # Stylesheets
│ │ ├── js/               # JavaScript files
│ │ └── img/              # Images and assets
│ └── templates/        # Jinja2 HTML templates
│   ├── auth/             # Authentication templates
│   ├── components/       # Reusable components
│   └── partials/         # Partial templates
├── tests/              # Unit and integration tests
├── .env                # Environment variables
├── alembic.ini         # Alembic configuration
├── main.py             # Application entry point
├── poetry.lock         # Poetry dependencies lock
├── pyproject.toml      # Project configuration
└── README.md           # Project documentation

ER Diagram

Here's the Entity-Relationship (ER) diagram for database:

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any changes.

License

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

Hybridhash/FastAPI-HTMX