SaaS Invoicing Application

A comprehensive SaaS invoicing solution built with FastAPI and SQLite for managing customers, invoices, and billing operations.

Features

• User Authentication: JWT-based authentication with secure registration and login
• Customer Management: Create, read, update, and delete customer records
• Invoice Management: Full invoice lifecycle management with automatic calculations
• Invoice Items: Line-item management with quantity, unit price, and total calculations
• Multiple Invoice Statuses: Draft, Sent, Paid, Overdue, and Cancelled
• Tax Calculations: Configurable tax rates with automatic tax amount calculations
• RESTful API: Comprehensive REST API with FastAPI documentation

Technology Stack

• Backend: FastAPI (Python)
• Database: SQLite with SQLAlchemy ORM
• Authentication: JWT tokens with passlib for password hashing
• API Documentation: Automatic OpenAPI/Swagger documentation
• Database Migrations: Alembic for database schema management
• Code Quality: Ruff for linting and code formatting

Environment Variables

The following environment variables should be set:

• SECRET_KEY - Secret key for JWT token signing (required for production)

Project Structure

├── main.py                 # FastAPI application entry point
├── requirements.txt        # Python dependencies
├── alembic.ini            # Alembic configuration
├── alembic/               # Database migrations
├── app/
│   ├── api/               # API route handlers
│   │   ├── auth.py        # Authentication endpoints
│   │   ├── users.py       # User management endpoints
│   │   ├── customers.py   # Customer management endpoints
│   │   ├── invoices.py    # Invoice management endpoints
│   │   └── routes.py      # Main API router
│   ├── core/              # Core functionality
│   │   ├── config.py      # Application configuration
│   │   ├── security.py    # Authentication and security
│   │   └── deps.py        # Dependency injection
│   ├── db/                # Database configuration
│   │   ├── base.py        # SQLAlchemy base class
│   │   └── session.py     # Database session management
│   ├── models/            # SQLAlchemy models
│   │   ├── user.py        # User model
│   │   ├── customer.py    # Customer model
│   │   └── invoice.py     # Invoice and InvoiceItem models
│   ├── schemas/           # Pydantic schemas
│   │   ├── user.py        # User schemas
│   │   ├── customer.py    # Customer schemas
│   │   └── invoice.py     # Invoice schemas
│   └── services/          # Business logic
│       ├── user_service.py      # User business logic
│       ├── customer_service.py  # Customer business logic
│       └── invoice_service.py   # Invoice business logic

Installation & Setup

1. Install dependencies:

pip install -r requirements.txt

2. Set environment variables:

export SECRET_KEY="your-secret-key-here"

3. Run database migrations:

alembic upgrade head

4. Start the application:

uvicorn main:app --reload

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

API Documentation

• Interactive API Documentation: http://localhost:8000/docs
• Alternative Documentation: http://localhost:8000/redoc
• OpenAPI Schema: http://localhost:8000/openapi.json
• Health Check: http://localhost:8000/health

API Endpoints

Authentication

• POST /auth/register - Register a new user
• POST /auth/login - Login user
• POST /auth/token - OAuth2 compatible token endpoint

Users

• GET /users/me - Get current user information
• PUT /users/me - Update current user information

Customers

• GET /customers/ - List all customers (paginated)
• POST /customers/ - Create a new customer
• GET /customers/{id} - Get customer by ID
• PUT /customers/{id} - Update customer
• DELETE /customers/{id} - Delete customer

Invoices

• GET /invoices/ - List all invoices (paginated)
• POST /invoices/ - Create a new invoice
• GET /invoices/{id} - Get invoice by ID
• PUT /invoices/{id} - Update invoice
• DELETE /invoices/{id} - Delete invoice
• PATCH /invoices/{id}/status - Update invoice status

Data Models

User

• ID, email, password, full name, company name
• Active status and timestamps

Customer

• ID, name, email, phone, address details
• Associated with user (multi-tenant)

Invoice

• ID, invoice number, customer, dates, status
• Subtotal, tax rate, tax amount, total
• Notes and timestamps

Invoice Items

• ID, invoice, description, quantity, unit price, total price

Database Storage

The application uses SQLite database stored at /app/storage/db/db.sqlite with automatic directory creation.

Security Features

• JWT token-based authentication
• Password hashing with bcrypt
• User isolation (multi-tenant data access)
• CORS enabled for cross-origin requests

Development

Code Quality

Run Ruff for linting and formatting:

ruff check .
ruff format .

Database Operations

Create new migration:

alembic revision --autogenerate -m "Description"

Apply migrations:

alembic upgrade head

Health Check

The application provides a health check endpoint at /health that returns:

{
  "status": "healthy",
  "service": "invoicing-api"
}

Production Deployment

1. Set a strong SECRET_KEY environment variable
2. Configure proper database backups for /app/storage/db/
3. Use a production WSGI server like Gunicorn
4. Set up proper logging and monitoring
5. Configure reverse proxy (nginx/Apache) if needed

License

This project is available for use in SaaS applications and business purposes.