saasinvoicingapplication-vgtx8z/README.md

# 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**:
   ```bash
   pip install -r requirements.txt
   ```

2. **Set Environment Variables**:
   ```bash
   export SECRET_KEY="your-super-secret-key-here"
   ```
   
   Required environment variables:
   - `SECRET_KEY`: JWT signing secret key (required for production)

3. **Run Database Migrations**:
   ```bash
   alembic upgrade head
   ```

4. **Start the Application**:
   ```bash
   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
```bash
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
```bash
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
```bash
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
```bash
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:
```bash
ruff check .
ruff format .
```

### Database Migrations
Create a new migration:
```bash
alembic revision --autogenerate -m "description"
```

Apply migrations:
```bash
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.