invoicegenerationservice-plrjlt/README.md

Invoice Generation Service

This is a FastAPI application for generating and managing invoices. It allows you to create, read, update, and delete invoices without requiring user signup.

Features

• Generate invoices with automatic invoice number generation
• Store invoice details in SQLite database
• Retrieve invoice information by ID or invoice number
• Update invoice details and status
• Delete invoices
• Web-based user interface for invoice management
• Health check endpoint

Technical Stack

• Framework: FastAPI
• Database: SQLite with SQLAlchemy ORM
• Migrations: Alembic
• Validation: Pydantic
• Frontend: Jinja2 Templates, HTML, CSS, JavaScript
• Linting: Ruff

Project Structure

.
├── alembic.ini               # Alembic configuration file
├── app                       # Application package
│   ├── api                   # API routes
│   │   └── routes            # API route modules
│   │       ├── __init__.py   # Routes initialization
│   │       ├── invoices.py   # Invoice API routes
│   │       └── frontend.py   # Frontend routes
│   ├── core                  # Core functionality
│   │   ├── config.py         # Application settings
│   │   ├── database.py       # Database connection setup
│   │   └── utils.py          # Utility functions
│   ├── models                # SQLAlchemy models
│   │   ├── __init__.py       # Models initialization
│   │   └── invoice.py        # Invoice and InvoiceItem models
│   ├── schemas               # Pydantic schemas
│   │   ├── __init__.py       # Schemas initialization
│   │   └── invoice.py        # Invoice-related schemas
│   ├── static                # Static files
│   │   ├── css               # CSS styles
│   │   │   └── styles.css    # Main stylesheet
│   │   └── js                # JavaScript files
│   │       └── main.js       # Main JavaScript file
│   └── templates             # Jinja2 templates
│       ├── base.html         # Base template with layout
│       ├── home.html         # Home page
│       ├── create_invoice.html # Invoice creation form
│       ├── search_invoice.html # Search for invoices
│       └── invoice_details.html # Invoice details page
├── main.py                   # Application entry point
├── migrations                # Alembic migrations
│   ├── env.py                # Alembic environment
│   ├── script.py.mako        # Migration script template
│   └── versions              # Migration scripts
│       └── ef0aaab3a275_initial_database_tables.py  # Initial migration
├── requirements.txt          # Project dependencies
└── pyproject.toml            # Ruff configuration

API Endpoints

Health Check

• GET /health: Check if the service is running

Invoice Management API

• POST /api/v1/invoices: Create a new invoice
• GET /api/v1/invoices: List all invoices (with pagination)
• GET /api/v1/invoices/{invoice_id}: Get a specific invoice by ID
• POST /api/v1/invoices/find: Find an invoice by invoice number
• PATCH /api/v1/invoices/{invoice_id}: Update an invoice
• PATCH /api/v1/invoices/{invoice_id}/status: Update invoice status
• DELETE /api/v1/invoices/{invoice_id}: Delete an invoice

Frontend Routes

• GET /: Home page with list of recent invoices
• GET /create: Form to create a new invoice
• POST /create: Process invoice creation form
• GET /search: Form to search for invoices by number
• POST /search: Process invoice search
• GET /invoice/{invoice_id}: View invoice details
• POST /invoice/{invoice_id}/status: Update invoice status

Setup and Installation

1. Clone the repository
2. Install dependencies:

   pip install -r requirements.txt
   

3. Run migrations:

   alembic upgrade head
   

4. Start the application:

   uvicorn main:app --reload
   

API Documentation

Once the application is running, you can access:

• Interactive API documentation at /docs (Swagger UI)
• Alternative API documentation at /redoc (ReDoc)

Web Interface

The application comes with a full web interface that allows users to:

• View a list of recent invoices on the home page
• Create new invoices using a dynamic form
• Search for existing invoices by invoice number
• View detailed invoice information
• Update invoice status (PENDING, PAID, CANCELLED)
• Print invoices

Invoice Number Format

Invoices are automatically assigned a unique invoice number with the format:

• INV-YYYYMM-XXXXXX, where:
  • INV is a fixed prefix
  • YYYYMM is the year and month (e.g., 202307 for July 2023)
  • XXXXXX is a random alphanumeric string