My SaaS Skeleton

A production-ready SaaS application skeleton built with the lessweb framework.

Features

• Admin Authentication: JWT-based authentication with Redis session management
• Database Management: MySQL with async operations via commondao ORM
• Database Migrations: Automated schema migrations using pyway
• Task Queue: Background job processing with BullMQ and Redis
• System Monitoring: Scheduled health checks for database connectivity
• API Documentation: Auto-generated OpenAPI/Swagger specifications
• Testing: Comprehensive E2E tests with pytest

Tech Stack

• Framework: lessweb (Python web framework with dependency injection)
• Database: MySQL with aiomysql async driver
• ORM: commondao (async MySQL toolkit with Pydantic integration)
• Cache/Queue: Redis with BullMQ for job scheduling
• Authentication: JWT tokens with bcrypt password hashing
• Testing: pytest with aiohttp test client

Quick Start

Prerequisites

• Python 3.11+
• MySQL 5.7+
• Redis 6.0+

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Configure environment:

cp .env.example .env
# Edit .env with your database and Redis credentials

3. Run database migrations:

make pyway-migrate

4. Start the application:

python main.py

The server will start at http://localhost:8080

Default Admin Credentials

• Username: admin
• Password: admin123

Important: Change the default password in production!

Development

Running Tests

# Run all tests
make test# Run with coverage
pytest tests --cov=src --cov-report=html
# Run linting
make lint

Database Migrations

# Create new migration# 1. Create migration file in migration/ directory following naming convention:# V{major}_{minor}_{patch}__{description}.sql# 2. Run migration
make pyway-migrate

OpenAPI Documentation

The OpenAPI specification is automatically updated on startup. To manually update:

make dump-openapi

In staging environment, access the OpenAPI spec at: http://localhost:8080/openapi/openapi.json

Project Structure

.
├── config/ # Configuration files (TOML format)
│ ├── mysql.toml
│ ├── redis.toml
│ ├── lessweb.toml
│ ├── bullmq.toml
│ └── jwt_gateway.toml
├── migration/ # Database migration scripts
├── openapi/ # OpenAPI specification
├── shared/ # Shared modules and plugins
│ ├── bullmq_plugin.py
│ ├── error_middleware.py
│ ├── jwt_gateway.py
│ ├── lessweb_commondao.py
│ └── redis_plugin.py
├── src/
│ ├── controller/ # API endpoints
│ ├── entity/ # Database models
│ ├── service/ # Business logic services
│ └── processor/ # Background job processors
├── tests/
│ └── e2e/ # End-to-end tests
├── main.py # Application entry point
└── Dockerfile # Docker container definition

API Endpoints

Authentication

• POST /login/admin - Admin login (returns JWT token)
• GET /admin/me - Get current admin info (requires auth)

Configuration

Environment-specific configurations are managed through:

• .env - Local development
• .env.testci - CI/CD testing
• .env.staging - Staging environment
• .env.production - Production environment

Configuration files in config/ can also have environment-specific versions:

• config/redis.production.toml - Production Redis with password

Background Jobs

The application uses BullMQ for scheduled tasks:

• Database Health Check (every 2 hours): Executes SELECT 1 to verify database connectivity

Docker Deployment

# Build image
docker build -t my-saas-skeleton .# Run container
docker run -p 8080:8080 --env-file .env.production my-saas-skeleton

License

MIT