saasinvoicingapplication-ee2b1b/README.md

# SaaS Invoicing Application

A comprehensive SaaS invoicing application built with FastAPI and SQLite, designed for businesses to manage organizations, clients, and invoices efficiently.

## Features

- **Multi-tenant Architecture**: Supports multiple organizations with user management
- **User Authentication**: Secure JWT-based authentication and role-based permissions
- **Organization Management**: Create and manage organizations with detailed information
- **Client Management**: Maintain a database of clients for each organization
- **Invoice Management**: Create, update, and delete invoices with line items
- **PDF Generation**: Generate professional PDF invoices for sharing with clients
- **API Documentation**: Interactive API documentation with Swagger UI and ReDoc

## Prerequisites

- Python 3.8+
- pip (Python package manager)

## Environment Variables

The application uses the following environment variables:

| Variable | Description | Default Value |
|----------|-------------|---------------|
| SECRET_KEY | Secret key for JWT token generation | CHANGE_ME_TO_A_SECURE_RANDOM_STRING |
| ACCESS_TOKEN_EXPIRE_MINUTES | Access token expiration time in minutes | 30 |
| SERVER_HOST | Host URL for the server | http://localhost:8000 |

## Installation

1. Clone the repository:

```bash
git clone https://github.com/yourusername/saasinvoicingapplication.git
cd saasinvoicingapplication
```

2. Create a virtual environment (optional but recommended):

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install dependencies:

```bash
pip install -r requirements.txt
```

4. Create a `.env` file with your environment variables:

```
SECRET_KEY=your-secure-secret-key
ACCESS_TOKEN_EXPIRE_MINUTES=30
SERVER_HOST=http://localhost:8000
```

5. Initialize the database:

```bash
mkdir -p /app/storage/db
python -c "from app.db.base import Base; from app.db.session import engine; Base.metadata.create_all(bind=engine)"
alembic upgrade head
```

## Running the Application

Start the application using uvicorn:

```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

The API will be available at:
- API: http://localhost:8000
- Swagger UI Documentation: http://localhost:8000/docs
- ReDoc Documentation: http://localhost:8000/redoc

## API Structure

The API follows a RESTful design and is structured as follows:

### Authentication Endpoints

- `POST /api/v1/auth/token` - Get access token
- `POST /api/v1/auth/test-token` - Test token validity

### User Management

- `GET /api/v1/users/` - List users (admin only)
- `POST /api/v1/users/` - Create user (admin only)
- `GET /api/v1/users/me` - Get current user info
- `PUT /api/v1/users/me` - Update current user
- `GET /api/v1/users/{user_id}` - Get user by ID
- `PUT /api/v1/users/{user_id}` - Update user (admin only)

### Organization Management

- `GET /api/v1/organizations/` - List organizations
- `POST /api/v1/organizations/` - Create organization (admin only)
- `GET /api/v1/organizations/{id}` - Get organization by ID
- `PUT /api/v1/organizations/{id}` - Update organization
- `DELETE /api/v1/organizations/{id}` - Delete organization (admin only)

### Client Management

- `GET /api/v1/clients/` - List clients
- `POST /api/v1/clients/` - Create client
- `GET /api/v1/clients/{id}` - Get client by ID
- `PUT /api/v1/clients/{id}` - Update client
- `DELETE /api/v1/clients/{id}` - Delete client

### Invoice Management

- `GET /api/v1/invoices/` - List invoices
- `POST /api/v1/invoices/` - Create invoice
- `GET /api/v1/invoices/{id}` - Get invoice by ID
- `PUT /api/v1/invoices/{id}` - Update invoice
- `DELETE /api/v1/invoices/{id}` - Delete invoice
- `GET /api/v1/invoices/{id}/pdf` - Generate PDF for invoice

## Data Models

### User

- `id`: Unique identifier
- `email`: Email address (unique)
- `full_name`: Full name
- `hashed_password`: Hashed password
- `is_active`: User status
- `is_superuser`: Admin status
- `organization_id`: Associated organization

### Organization

- `id`: Unique identifier
- `name`: Organization name
- `address`, `city`, `state`, `postal_code`, `country`: Address information
- `phone`, `email`, `website`: Contact information
- `tax_id`: Tax identification number
- `logo_url`: URL to organization logo

### Client

- `id`: Unique identifier
- `name`: Client name
- `contact_name`: Primary contact
- `email`, `phone`: Contact information
- `address`, `city`, `state`, `postal_code`, `country`: Address information
- `tax_id`: Tax identification number
- `notes`: Additional notes
- `organization_id`: Associated organization
- `created_by_id`: User who created the client

### Invoice

- `id`: Unique identifier
- `invoice_number`: Invoice reference number
- `status`: Invoice status (draft, sent, paid, overdue, cancelled)
- `issue_date`, `due_date`: Invoice dates
- `subtotal`, `tax_rate`, `tax_amount`, `discount`, `total`: Financial information
- `notes`, `terms`: Additional information
- `is_recurring`, `recurring_interval`: Recurring invoice details
- `client_id`: Associated client
- `organization_id`: Associated organization
- `created_by_id`: User who created the invoice

### InvoiceItem

- `id`: Unique identifier
- `description`: Item description
- `quantity`, `unit_price`, `amount`: Item details
- `invoice_id`: Associated invoice

## Development

### Running Tests

Run tests using pytest:

```bash
pytest
```

### Database Migrations

Generate a new migration after model changes:

```bash
alembic revision --autogenerate -m "Description of changes"
```

Apply migrations:

```bash
alembic upgrade head
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.