Lodestone-API

A comprehensive FastAPI application for file upload and management with MinIO storage, PostgreSQL database, Redis caching, and Celery task processing.

Features

• 🔐 JWT Authentication & Authorization
• 📁 File Upload & Management with MinIO
• 🗃️ PostgreSQL Database with SQLAlchemy ORM
• 🔧 Database Migrations with Alembic
• 🔄 Async Task Processing with Celery & Redis
• 🧪 Comprehensive Testing Suite
• 🐳 Docker & Docker Compose Setup
• 📦 UV Package Management

Quick Start

Prerequisites

• Docker & Docker Compose
• Python 3.11+
• UV (for local development)

Running with Docker

1. Clone the repository:

git clone https://github.com/conorburke/lodestone-api.git
cd lodestone-api

2. Set up environment variables:

cp .env.example .env
# Edit .env with your configurations

3. Start all services:

make build
make up

4. Run database migrations:

make mmigrate

4. The API will be available at http://localhost:8000

5. MinIO Console at http://localhost:9001

API Endpoints

Authentication

• POST /api/v1/auth/register - Register new user
• POST /api/v1/auth/login - Login user
• GET /api/v1/auth/me - Get current user info

Files

• POST /api/v1/files/upload - Upload file
• GET /api/v1/files/ - List user files
• GET /api/v1/files/{file_id} - Get file details
• GET /api/v1/files/{file_id}/download - Get download URL
• DELETE /api/v1/files/{file_id} - Delete file

Testing

Run the test suite:

make test

Architecture

Services

• FastAPI: Web framework and API server
• PostgreSQL: Primary database for metadata and users
• MinIO: S3-compatible object storage for files
• Redis: Message broker and caching for worker jobs
• Celery: Async task processing

Project Structure

app/
├── api/          # API route handlers
├── core/         # Core functionality (auth, storage)
├── models/       # SQLAlchemy models
├── schemas/      # Pydantic schemas
├── tasks/        # Celery tasks
└── workers/      # Celery configuration

Database Migrations

Create a new migration:

make create-migration msg="<migration-name>"

Apply migrations:

make migrate

Monitoring & Health Checks

• Health check endpoint: GET /health
• API documentation: http://localhost:8000/docs
• MinIO console: http://localhost:9001

Security

• JWT-based authentication
• Password hashing with bcrypt
• File size limits (100MB default)
• CORS configuration for frontend integration

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License