Documentation for Invoicing System Design

Types of Documentation Required

• Functional Specifications: Describes the functional requirements of the system, such as managing multiple journals, supporting different activities, and applying various templates for each trade name.
• Technical Specifications: Details the technology and architecture for building the system, including programming languages, databases, and integration with other systems.
• User Manuals: Essential for end users to understand system usage, including creating journals, adding activities, and selecting templates for different trade names.
• Template Designs: Separate designs for each activity and trade name, specifying layout, fields, and style for each template.
• Security Policy: Documentation on user data protection, including access control, data encryption, and privacy regulation compliance.
• Test Plans and Scenarios: Detailed test cases for system functionality and reliability, including tests for different templates and activities.
• Integration Guides: Necessary for integrating the system with other software or services, such as accounting systems or payment platforms.
• Maintenance and Support Documentation: Information on system maintenance, troubleshooting, and user support.

 

Functional Specifications Framework

Developing functional specifications for an invoicing system organized by journal and supporting different activities with separate templates is a detailed process. A basic framework is provided for adaptation and use according to specific needs.

Functional Specifications for an Invoicing System

Introduction

Purpose of the Document

This document outlines the functional requirements for an invoicing system designed to manage various activities, each with its own journal and templates, across multiple trade names.

Target Audience

This document is intended for the development team, project managers, and stakeholders involved in the implementation of the invoicing system.

System Overview

General Description

The system will enable users to generate, manage, and send invoices, organized by different activities and trade names. Each journal and activity will have its own template for invoicing.

Functional Requirements

1. Journal Management

• 1.1 Creation and Management of Journals: Users should be able to create and manage multiple journals, each linked to specific activities or trade names.
• 1.2 Journal Selection: When creating an invoice, the user should be able to select a relevant journal.

2. Activity Management

• 2.1 Creation of Activities: Users should be able to define activities and link them to specific trade names.
• 2.2 Activity-Specific Invoicing: Each activity should have a separate template for invoicing.
• 2.3 Export to PDFWeasyprint https://doc.courtbouillon.org/weasyprint/stable/api_reference.html
• 2.4 Send invoice by Email
• 2.5 Send Reminder by Email
• 2.6 Filter unpaid invoices
• 2.7 Dashboard per activity Turnover, Total Outstanding Receivables, Average No. of Days for Getting Paid, Due Within 30 Days, Sales and Expenses, Total Sales, Total Receipts, Received Payments
• 2.8 Received Payments
• 2.9 Estimates is like invoice but it not going in accounting
• 2.10 Customers
• 2.11 Products / Items per activiteit

3. Template Management

• 3.1 Designing Templates: Ability to design custom templates for each activity.
• 3.2 Template Selection: Automatic selection of the correct template based on the chosen activity or trade name.

4. Invoicing

• 4.1 Creation of Invoices: Creating invoices with preset or custom fields.
• 4.2 Invoice Dispatch: Options for electronically sending invoices to customers.

5. User Interface and Accessibility

• 5.1 Intuitive User Interface: A user-friendly interface that facilitates navigation and management of different journals and activities.
• 5.2 Multilingual Support: Support for multiple languages, if necessary.

6. Security and Compliance

• 6.1 Data Security: Strong security measures for the protection of user data.
• 6.2 Compliance: Adherence to relevant laws and regulations regarding invoicing and data protection.

7. Integrations

• 7.1 Integration with Accounting Systems: Capability to integrate with existing accounting systems.
• 7.2 API Support: Open APIs for future integrations and expansions.

Conclusion

This document provides an overview of the functional requirements for developing a versatile and efficient invoicing system, tailored to the needs of organizations operating with multiple trade names and activities.

This framework is only a starting point and should be further customized and detailed based on the specific requirements and circumstances of your project.

Technical Specifications for Invoicing System

Overview

This document outlines the technical architecture and specifications for the development of an invoicing system designed to manage various business activities and transactions.

System Architecture

1. Software Architecture

The invoicing system will be based on a multi-tier architecture, comprising a client layer, server layer, and database layer.

2. Hardware Requirements

The system will be designed to be compatible with standard business hardware, including personal computers and mobile devices.

Programming Languages and Frameworks

• Front-End Development: HTMLX, CSS3, JavaScript ( Vue.js ) If it working in admin then we could try to create Vue site with builder like that https://www.weweb.io/ or this one but there are componet libs https://www.telerik.com/try/kendo-vue-ui for shops https://www.ycombinator.com/companies/vue-storefront Tailwind UI fo Vue.Js
• Back-End Development: Python (Django) First version only admin and generators then views with TailwindUI and HTMX maybe Jquery if needed

Database Management

• Database System: SQL-based (PostgreSQL)
• Data Storage: Cloud storage solutions wher Quickbooks.site installed on-premises servers.

Integration and APIs

• APIs: RESTful APIs for system integration and data exchange. In next version now is only Admin
• External Integrations: Integration capabilities with existing accounting software, CRM systems, and payment gateways. Not needed we do only cars and HR sectors

Security Specifications

• Data Encryption: Use of SSL/TLS for data transmission and AES for data at rest.
• User Authentication: Implementation of OAuth 2.0 or similar protocols for secure user authentication. We extend Quickbooks.site and users
• Compliance: Adherence to relevant data protection regulations (e.g., GDPR, HIPAA).

Performance and Scalability

• Load Balancing: Use of load balancers to distribute traffic and ensure system responsiveness. Not needed in first version but Quickbooks have al ready right infrostructure
• Scalability: Scalable architecture to handle increasing user load and data volume.

Testing and Quality Assurance

• Unit Testing: Comprehensive unit tests to cover individual components and functions.
• Integration Testing: Testing of integrated modules to ensure seamless functionality.
• Performance Testing: Regular load and stress tests to evaluate system performance under various conditions.

Deployment and Maintenance

• Deployment Strategy: Continuous integration and deployment (CI/CD) pipeline for efficient software delivery.
• Maintenance Plan: Regular updates and maintenance schedule for system optimization and security patching.

Conclusion

This document provides a comprehensive overview of the technical specifications for the invoicing system. It is intended to guide the development team through the system architecture, choice of technologies, and essential security measures.

These specifications are designed to ensure the development of a robust, secure, and scalable invoicing system that meets the business's operational needs.

Django Models for Invoicing Application

Product Model

Field	Type	Description
name	CharField	Product name
price	DecimalField	Product price
description	TextField	Product description

Customer Model

Field	Type	Description
name	CharField	Customer name
email	EmailField	Customer email
address	TextField	Customer address

Estimate Model

Field	Type	Description
customer	ForeignKey	Link to Customer
estimate_date	DateField	Date of estimate
estimated_amount	DecimalField	Estimated amount

Invoice Model

Field	Type	Description
customer	ForeignKey	Link to Customer
issue_date	DateField	Date of invoice issue
due_date	DateField	Invoice due date
total_amount	DecimalField	Total amount of invoice
products	ManyToManyField	Link to Products

InvoiceProduct Model

Field	Type	Description
invoice	ForeignKey	Link to Invoice
product	ForeignKey	Link to Product
quantity	PositiveIntegerField	Quantity of product

Payment Model

Field	Type	Description
invoice	ForeignKey	Link to Invoice
payment_date	DateField	Date of payment
amount	DecimalField	Payment amount

Django Models for Invoicing System

Product Model

        
class Product(models.Model):
    name = models.CharField(max_length=200)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    description = models.TextField(blank=True)

    def __str__(self):
        return self.name
        
    

Customer Model

        
class Customer(models.Model):
    name = models.CharField(max_length=200)
    email = models.EmailField()
    address = models.TextField()

    def __str__(self):
        return self.name
        
    

Estimate Model

        
class Estimate(models.Model):
    customer = models.ForeignKey(Customer, on_delete=models.CASCADE)
    estimate_date = models.DateField()
    estimated_amount = models.DecimalField(max_digits=10, decimal_places=2)

    def __str__(self):
        return f"Estimate for {self.customer.name} on {self.estimate_date}"
        
    

Invoice Model

        
class Invoice(models.Model):
    customer = models.ForeignKey(Customer, on_delete=models.CASCADE)
    issue_date = models.DateField()
    due_date = models.DateField()
    total_amount = models.DecimalField(max_digits=10, decimal_places=2)
    products = models.ManyToManyField(Product, through='InvoiceProduct')

    def __str__(self):
        return f"Invoice {self.id} for {self.customer.name}"
        
    

InvoiceProduct Model

        
class InvoiceProduct(models.Model):
    invoice = models.ForeignKey(Invoice, on_delete=models.CASCADE)
    product = models.ForeignKey(Product, on_delete=models.CASCADE)
    quantity = models.PositiveIntegerField()

    def __str__(self):
        return f"{self.quantity} x {self.product.name} in Invoice {self.invoice.id}"
        
    

Payment Model

        
class Payment(models.Model):
    invoice = models.ForeignKey(Invoice, on_delete=models.CASCADE)
    payment_date = models.DateField()
    amount = models.DecimalField(max_digits=10, decimal_places=2)

    def __str__(self):
        return f"Payment of {self.amount} for Invoice {self.invoice.id}"
        
    

Revised Django Models for Invoicing System

Journal Model

        
class Journal(models.Model):
    name = models.CharField(max_length=100)
    description = models.TextField(blank=True)
    template_content = models.TextField()  # Text-based templates

    def __str__(self):
        return self.name
        
    

Invoice Model

        
class Invoice(models.Model):
    journal = models.ForeignKey(Journal, on_delete=models.CASCADE)
    series_number = models.IntegerField()
    issue_date = models.DateField()
    due_date = models.DateField()
    total_amount = models.DecimalField(max_digits=10, decimal_places=2)
    # ... other fields ...

    def __str__(self):
        return f"{self.journal.name}-{self.series_number}"

    class Meta:
        unique_together = ('journal', 'series_number')
        
    

Auto-Incrementing Series Numbers

Example function to determine the next series number for a new invoice in a given journal:

        
def get_next_series_number(journal):
    last_invoice = Invoice.objects.filter(journal=journal).order_by('series_number').last()
    if last_invoice:
        return last_invoice.series_number + 1
    return 1

# Usage example for creating a new invoice
journal = Journal.objects.get(id=journal_id)
new_series_number = get_next_series_number(journal)
new_invoice = Invoice(journal=journal, series_number=new_series_number, ...)
new_invoice.save()
        
    

Django Admin Configuration for Invoicing System

Product Admin Configuration

        
@admin.register(Product)
class ProductAdmin(admin.ModelAdmin):
    list_display = ('name', 'price', 'description')
        
    

Customer Admin Configuration

        
@admin.register(Customer)
class CustomerAdmin(admin.ModelAdmin):
    list_display = ('name', 'email', 'address')
        
    

Estimate Admin Configuration

        
@admin.register(Estimate)
class EstimateAdmin(admin.ModelAdmin):
    list_display = ('customer', 'estimate_date', 'estimated_amount')
    list_filter = ('estimate_date',)
    search_fields = ('customer__name',)
        
    

Invoice Admin Configuration

        
@admin.register(Invoice)
class InvoiceAdmin(admin.ModelAdmin):
    list_display = ('customer', 'issue_date', 'due_date', 'total_amount')
    list_filter = ('issue_date', 'due_date')
    search_fields = ('customer__name',)
        
    

InvoiceProduct Admin Configuration

        
@admin.register(InvoiceProduct)
class InvoiceProductAdmin(admin.ModelAdmin):
    list_display = ('invoice', 'product', 'quantity')
    list_filter = ('invoice',)
    search_fields = ('product__name',)
        
    

Payment Admin Configuration

        
@admin.register(Payment)
class PaymentAdmin(admin.ModelAdmin):
    list_display = ('invoice', 'payment_date', 'amount')
    list_filter = ('payment_date',)
    search_fields = ('invoice__id',)
        
    

Django code generators

https://djangobuilder.io/#/
https://github.com/sageteam-org/django-sage-painless
https://github.com/Abdenasser/dr_scaffold

DRF

refers to a framework that adheres to a set of principles enabling the creation of scalable, stateless, and cacheable APIs. Being open-source, it offers extensive customizability. The framework is equipped with features such as serialization for models, viewsets to manage controller logic, and routers to establish URL patterns.

https://github.com/tfranzel/drf-spectacular
https://github.com/tfranzel/drf-spectacular-sidecar

Swagger

Swagger streamlines the build process by automatically generating server stubs and client SDKs for APIs described using the OpenAPI (formerly Swagger) specification. This allows your team to concentrate more effectively on implementing and adopting your API, rather than on these initial setup tasks.
https://github.com/swagger-api/swagger-ui
https://django-rest-swagger.readthedocs.io/en/latest/
https://swagger.io/tools/swagger-codegen/
https://www.youtube.com/watch?v=XBxssKYf5G0

Use Cases of Django Channels in an Invoicing System

1. Real-time Notifications

Implement Django Channels to send instant notifications when new invoices are generated, approved, or paid, without requiring page refreshes.

2. Live Dashboard Updates

Use Django Channels to provide live updates on the dashboard for changing invoice statuses, enhancing real-time data visibility.

3. Collaborative Invoice Editing

Facilitate real-time, collaborative editing of invoices, allowing multiple users to view and edit simultaneously with updates synchronizing instantly.

4. Chat Support for Customer Service

Integrate a live chat feature within the invoicing system for real-time communication between users and customer support, powered by Django Channels.

5. Asynchronous Report Generation

Manage time-consuming financial report generation tasks asynchronously, notifying users upon completion to enhance user experience.

6. Subscription-Based Updates

Handle real-time updates for clients subscribed to specific invoice changes, such as payment status updates or reminders.

7. Real-time Data Feeds

Update real-time external data feeds, such as exchange rates or stock levels, within the application using Django Channels.

Conclusion

Django Channels is an invaluable tool for real-time features in complex invoicing systems, requiring a solid understanding of asynchronous programming and WebSockets.

Benefits of Using HTMX and django-htmx in an Invoice Project

1. Simplifying AJAX Calls

HTMX allows easy implementation of AJAX calls directly within HTML, simplifying dynamic page updates like invoice list refreshes without full page reloads.

2. Enhancing User Experience

Interactive and responsive interfaces are more achievable with HTMX, offering features like real-time form validations and dynamic content loading.

3. Reducing JavaScript Complexity

HTMX reduces the need for extensive JavaScript, enabling simpler and more maintainable codebases by handling many interactions in HTML.

4. Streamlining Front-End Development

Developers can create dynamic web pages more comfortably using HTML attributes provided by HTMX, without deep JavaScript knowledge.

5. Seamless Integration with Django

django-htmx provides tools for easy integration of HTMX's features into Django projects, enhancing Django's capabilities for dynamic web development.

6. Faster Development

HTMX enables quicker development and prototyping by allowing rapid implementation of dynamic behaviors with minimal code changes.

7. Backend-Focused Development

HTMX caters to teams skilled in Django, allowing them to create dynamic web applications while focusing on backend development.

Conclusion

For an invoicing system, HTMX and django-htmx provide a path to dynamic and modern web applications with less complexity, leading to quicker development, easier maintenance, and a more streamlined development experience. This is especially interesting for first steps when we use MVP and determine what is needed and what it should look like.

Links

https://htmx.org/examples/
https://htmx.org/
https://github.com/adamchainz/django-htmx
https://hyperview.org/ Simple
https://hyperscript.org/
https://getuikit.com/ Very nice small UI lib for MVP and Admin usage. 

Best Phone Field Type in Django

1. Using CharField with Validation

Use a CharField and add custom validation for phone numbers.

from django.db import models
from django.core.validators import RegexValidator

class MyModel(models.Model):
    phone_regex = RegexValidator(regex=r'^\+?1?\d{9,15}$',
                                 message="Phone number must be entered in the format: '+999999999'. Up to 15 digits allowed.")
    phone_number = models.CharField(validators=[phone_regex], max_length=17, blank=True)

2. Using Third-Party Packages

Utilize the django-phonenumber-field package for robust phone number handling.

from django.db import models
from phonenumber_field.modelfields import PhoneNumberField

class MyModel(models.Model):
    phone_number = PhoneNumberField(null=False, blank=False, unique=True)

3. Custom ModelField

Create a custom ModelField for specific requirements.

4. Storing as IntegerField

A less common approach, generally not recommended due to loss of information.

Conclusion

The choice depends on the specific requirements. For simple cases, CharField with custom validation is sufficient. For more complex scenarios, especially international formats, django-phonenumber-field is recommended. For unique requirements, a custom ModelField might be the best solution.

Invoice Comments and History System Models

InvoiceLog Model

This model represents the logs or comments associated with each invoice.

        
from django.db import models
from django.contrib.auth.models import User

class Invoice(models.Model):
    # ... your existing Invoice fields ...
    pass

class InvoiceLog(models.Model):
    invoice = models.ForeignKey(Invoice, on_delete=models.CASCADE, related_name='logs')
    created_at = models.DateTimeField(auto_now_add=True)
    updated_by = models.ForeignKey(User, on_delete=models.SET_NULL, null=True)
    action = models.CharField(max_length=255)
    comment = models.TextField(blank=True, null=True)

    def __str__(self):
        return f"Log for Invoice {self.invoice.id} - {self.action}"

    class Meta:
        ordering = ['-created_at']
        
    

Explanation:

• invoice: A ForeignKey linking the log to a specific invoice.
• created_at: A DateTimeField that automatically sets the date and time when a log is created.
• updated_by: A ForeignKey to Django’s User model, indicating which user created or updated the log.
• action: A CharField to describe the action taken.
• comment: A TextField for any additional comments or details about the action.

Additional Considerations:

• Ensure that only authorized users can add or modify logs.
• Automate the creation of certain types of logs based on invoice activities.
• Consider how these logs will be presented in the application’s user interface.

Model Updates for Capturing Snapshots in an Invoice System

To ensure that customer information and product details in old invoices remain unchanged even if the product or customer information is updated later, the models are structured to capture and store a snapshot of this information at the time the invoice is created.

Updated Models

1. Customer Model

This model represents your customers. When customer details change, you update this model, but it won't affect existing invoices.

class Customer(models.Model):
    name = models.CharField(max_length=100)
    email = models.EmailField()
    address = models.TextField()
    # other customer fields
    

2. Product Model

This model represents your products. Like the Customer model, changes here won't affect existing invoices.

class Product(models.Model):
    name = models.CharField(max_length=100)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    # other product fields
    

3. Invoice Model

The Invoice model will reference the Customer model, but it will store customer information at the time of invoice creation as a snapshot.

class Invoice(models.Model):
    customer = models.ForeignKey(Customer, on_delete=models.CASCADE)
    customer_snapshot = models.JSONField()  # Stores a snapshot of customer details
    issue_date = models.DateField()
    # other invoice fields
    

4. InvoiceItem Model

Instead of linking directly to the Product model, this model will store a snapshot of the product details at the time of invoice creation.

class InvoiceItem(models.Model):
    invoice = models.ForeignKey(Invoice, related_name='items', on_delete=models.CASCADE)
    product_snapshot = models.JSONField()  # Stores a snapshot of product details
    quantity = models.IntegerField()
    # other fields as necessary, such as price, discount, etc.
    

Implementation Details

• Creating an Invoice: When you create an invoice, you'll pull the current data from the Customer and Product models and save it as a JSON snapshot in 'customer_snapshot' and 'product_snapshot' fields. This way, the invoice retains the information as it was at the time of its creation.
• JSONField: The 'JSONField' is used to store a snapshot of the customer and product details. This field is flexible enough to store a dictionary of attributes (like name, price, address, etc.).
• Data Integrity: Ensure that the snapshot data is correctly captured at the time of invoice creation. It's crucial for maintaining accurate historical data.

Example

When creating an invoice and its items, you would do something like this:

def create_invoice(customer_id, product_ids_quantities):
    customer = Customer.objects.get(id=customer_id)
    customer_data = {
        'name': customer.name,
        'email': customer.email,
        'address': customer.address
        # include other relevant fields
    }

    invoice = Invoice.objects.create(
        customer=customer,
        customer_snapshot=customer_data,
        # other fields
    )

    for product_id, quantity in product_ids_quantities.items():
        product = Product.objects.get(id=product_id)
        product_data = {
            'name': product.name,
            'price': str(product.price)  # Convert Decimal to string for JSON serialization
            # include other relevant fields
        }

        InvoiceItem.objects.create(
            invoice=invoice,
            product_snapshot=product_data,
            quantity=quantity,
            # other fields
        )

    return invoice
    

This approach ensures that even if you change the details of a customer or a product later, the invoices and their items will retain the information as it was at the time of their creation.

Updating Invoice Model for Status and Payment Tracking

Adding a status field and tracking the amount paid are crucial for managing the invoice lifecycle and financial reporting in an invoicing system. Here's an update to the Invoice model that includes these features:

Updated Invoice Model with Status and Amount Paid

from django.db import models

class Invoice(models.Model):
    # Existing fields like customer, issue_date, etc.

    class InvoiceStatus(models.TextChoices):
        DRAFT = 'DR', 'Draft'
        SENT = 'SE', 'Sent'
        PAID = 'PA', 'Paid'
        # Add more statuses as needed

    status = models.CharField(
        max_length=2,
        choices=InvoiceStatus.choices,
        default=InvoiceStatus.DRAFT,
    )

    amount_paid = models.DecimalField(max_digits=10, decimal_places=2, default=0)

    # rest of the fields and methods
    

Explanation

• InvoiceStatus: An inner class defining different possible states for an invoice using TextChoices for readability and ease of use.
• status: A CharField with choices set to InvoiceStatus.choices to restrict the values to the predefined statuses. The default status is 'Draft'.
• amount_paid: A DecimalField to store the total amount paid. It defaults to 0 and is updated as payments are received.

Handling Invoice Payments

When a payment is made against an invoice, the amount_paid field and possibly the status field are updated. For full payments, the status may change to 'Paid'.

Additional Considerations

• Handling partial payments and determining conditions for status changes.
• Managing overpayments and refunds scenarios.
• Automating status updates based on certain triggers or actions.
• Using the new fields for improved reporting and analytics on invoice statuses and finances.

These enhancements will significantly improve the functionality of your invoicing system, allowing for more accurate tracking of each invoice's status and financials.