saasinvoicingapplication-xfyrsz/README.md

# SaaS Invoicing Application

A comprehensive invoicing solution for businesses built with FastAPI and SQLite.

## Features

- **User Authentication**: JWT-based authentication system
- **Client Management**: Create, read, update, and delete clients
- **Invoice Management**: Full CRUD operations for invoices with line items
- **Health Monitoring**: Built-in health check endpoint
- **API Documentation**: Interactive API docs with Swagger UI

## Tech Stack

- **Backend**: FastAPI
- **Database**: SQLite with SQLAlchemy ORM
- **Authentication**: JWT tokens with bcrypt password hashing
- **Migrations**: Alembic
- **Code Quality**: Ruff for linting and formatting

## Project Structure

```
├── main.py                 # FastAPI application entry point
├── requirements.txt        # Python dependencies
├── alembic.ini            # Alembic configuration
├── migrations/            # Database migrations
├── app/
│   ├── core/              # Core functionality (auth, config)
│   ├── db/                # Database configuration
│   ├── models/            # SQLAlchemy models
│   ├── routers/           # API route handlers
│   └── schemas/           # Pydantic schemas
```

## Installation

1. Install dependencies:
```bash
pip install -r requirements.txt
```

2. Set up environment variables:
```bash
export SECRET_KEY="your-secret-key-here"
```

3. Run database migrations:
```bash
alembic upgrade head
```

4. Start the application:
```bash
uvicorn main:app --reload
```

## Environment Variables

- `SECRET_KEY`: JWT secret key for token signing (required)

## API Endpoints

### Authentication
- `POST /auth/login` - User login

### Users
- `POST /users/register` - Register new user
- `GET /users/me` - Get current user profile

### Clients
- `POST /clients/` - Create new client
- `GET /clients/` - List all clients
- `GET /clients/{id}` - Get specific client
- `PUT /clients/{id}` - Update client
- `DELETE /clients/{id}` - Delete client

### Invoices
- `POST /invoices/` - Create new invoice
- `GET /invoices/` - List all invoices
- `GET /invoices/{id}` - Get specific invoice
- `PUT /invoices/{id}` - Update invoice
- `DELETE /invoices/{id}` - Delete invoice

### Health
- `GET /health` - Application health check

## API Documentation

Once the application is running, you can access:
- Interactive API docs: http://localhost:8000/docs
- ReDoc documentation: http://localhost:8000/redoc
- OpenAPI JSON: http://localhost:8000/openapi.json

## Database

The application uses SQLite database stored at `/app/storage/db/db.sqlite`. The database includes tables for:
- Users (authentication and profile data)
- Clients (customer information)
- Invoices (invoice headers)
- Invoice Items (line items for invoices)

## Development

### Code Quality
```bash
# Run linting and formatting
ruff check .
ruff format .
```

### Database Migrations
```bash
# Create new migration
alembic revision --autogenerate -m "Description"

# Apply migrations
alembic upgrade head
```

## Usage Example

1. Register a new user:
```bash
curl -X POST "http://localhost:8000/users/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123",
    "full_name": "John Doe",
    "company_name": "ACME Corp"
  }'
```

2. Login to get access token:
```bash
curl -X POST "http://localhost:8000/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'
```

3. Create a client (use the token from step 2):
```bash
curl -X POST "http://localhost:8000/clients/" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client Company",
    "email": "client@example.com",
    "phone": "+1234567890",
    "address": "123 Main St, City, State 12345"
  }'
```

4. Create an invoice:
```bash
curl -X POST "http://localhost:8000/invoices/" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-001",
    "client_id": 1,
    "due_date": "2024-02-01T00:00:00",
    "tax_rate": 8.5,
    "items": [
      {
        "description": "Web Development Services",
        "quantity": 40,
        "unit_price": 75.00
      }
    ]
  }'
```

## License

This project is licensed under the MIT License.