SaaS Invoicing Application

A comprehensive SaaS invoicing application built with FastAPI, SQLAlchemy, and SQLite. This application provides a complete invoicing solution with user authentication, customer management, invoice creation, and PDF generation capabilities.

Features

• User Authentication: JWT-based authentication with registration and login
• Customer Management: Full CRUD operations for customer data
• Invoice Management: Create, update, and manage invoices with line items
• PDF Generation: Generate professional PDF invoices for download
• RESTful API: Well-structured REST API with OpenAPI documentation
• Database Management: SQLite database with Alembic migrations
• Security: Password hashing, JWT tokens, and user-based data isolation

Technology Stack

• Backend: FastAPI
• Database: SQLite with SQLAlchemy ORM
• Authentication: JWT tokens with python-jose
• PDF Generation: ReportLab
• Migrations: Alembic
• Password Hashing: Passlib with bcrypt
• Code Quality: Ruff for linting and formatting

Installation & Setup

1. Install Dependencies:

   pip install -r requirements.txt
   

2. Set Environment Variables:

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

   Required environment variables:

   • SECRET_KEY: JWT signing secret key (required for production)

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 Docs: http://localhost:8000/docs
• ReDoc Documentation: http://localhost:8000/redoc
• OpenAPI Schema: http://localhost:8000/openapi.json

API Endpoints

Authentication

• POST /auth/register - Register a new user
• POST /auth/login - Login and get access token

Customers

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

Invoices

• GET /invoices/ - List all invoices (authenticated)
• POST /invoices/ - Create a new invoice
• GET /invoices/{id} - Get invoice details
• PUT /invoices/{id} - Update invoice
• DELETE /invoices/{id} - Delete invoice
• GET /invoices/{id}/pdf - Download invoice as PDF

Health & Info

• GET / - Application info and links
• GET /health - Health check endpoint

Database Schema

Users

• id, email, full_name, company_name, hashed_password, is_active
• One-to-many relationships with customers and invoices

Customers

• id, name, email, phone, address, city, country, postal_code
• Belongs to a user

Invoices

• id, invoice_number, issue_date, due_date, status, amounts, notes
• Belongs to a user and customer
• Has many invoice items

Invoice Items

• id, description, quantity, unit_price, total_price
• Belongs to an invoice

Authentication

The API uses JWT (JSON Web Tokens) for authentication:

1. Register a new user or login with existing credentials
2. Include the JWT token in the Authorization header: Authorization: Bearer <token>
3. Tokens expire after 30 minutes (configurable)

Usage Examples

Register a new user

curl -X POST "http://localhost:8000/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secret123",
    "full_name": "John Doe",
    "company_name": "Acme Corp"
  }'

Login

curl -X POST "http://localhost:8000/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@example.com&password=secret123"

Create a customer

curl -X POST "http://localhost:8000/customers/" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client Company",
    "email": "client@example.com",
    "address": "123 Main St",
    "city": "New York",
    "country": "USA"
  }'

Create an invoice

curl -X POST "http://localhost:8000/invoices/" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-2024-001",
    "issue_date": "2024-01-15T00:00:00Z",
    "due_date": "2024-02-15T00:00:00Z",
    "customer_id": 1,
    "status": "draft",
    "subtotal": 1000.00,
    "tax_rate": 10.00,
    "tax_amount": 100.00,
    "total_amount": 1100.00,
    "items": [
      {
        "description": "Web Development Services",
        "quantity": 40,
        "unit_price": 25.00,
        "total_price": 1000.00
      }
    ]
  }'

Development

Code Quality

Run Ruff for linting and formatting:

ruff check .
ruff format .

Database Migrations

Create a new migration:

alembic revision --autogenerate -m "description"

Apply migrations:

alembic upgrade head

Project Structure

├── main.py                 # FastAPI application entry point
├── requirements.txt        # Python dependencies
├── alembic.ini            # Alembic configuration
├── alembic/               # Database migrations
├── app/
│   ├── core/              # Core functionality (auth, config, deps)
│   ├── db/                # Database configuration
│   ├── models/            # SQLAlchemy models
│   ├── routers/           # API route handlers
│   ├── schemas/           # Pydantic models
│   └── services/          # Business logic and CRUD operations
└── /app/storage/          # Application file storage
    └── db/                # SQLite database location

Environment Variables

The following environment variables can be configured:

• SECRET_KEY: JWT signing secret (required for production)
• ACCESS_TOKEN_EXPIRE_MINUTES: Token expiration time (default: 30)

Set these in your production environment for security.

License

This project is created by BackendIM for SaaS invoicing management.