accounting/AGENTS.md

About This Project

This project is used to create invoices from Gitea issues and send them to customers. It can be operated via a CLI or a REST API.

Development Workflow

Dependencies

This project requires a running instance of Gotenberg for PDF generation. You can start it with Docker:

docker run --rm -p 3030:3000 gotenberg/gotenberg:8

Running the Application

The project contains two main applications:

• API Server: go run ./cmd/invoiceapi/main.go
• CLI Tool: go run ./cmd/invoicer/main.go <command>

Alternatively, you can use Docker for a containerized environment:

docker-compose up --build

Running Tests

To run all tests for the project, use the following command:

go test ./...

Code Formatting

To format the code according to the project's standards, run:

go fmt ./...

Project Conventions

Commit Messages

This project follows the Conventional Commits specification. Please ensure your commit messages adhere to this format.

Dependencies and Libraries

• Prefer the Go standard library over external dependencies whenever possible.
• Do not add any third-party testing libraries. All tests should use the built-in testing package.

Directory Structure

This section provides an overview of the project's directory structure to guide you on where to place new code.

• /cmd: Main application entry points. Each subdirectory is a separate executable.

  • invoiceapi: The REST API server.
  • invoicer: The command-line interface (CLI) tool.

• /internal: Contains all the private application and business logic. Code in this directory is not meant to be imported by other projects.

  • api: Defines the API layer, including HTTP handlers, routes, and request/response models.
  • config: Handles loading and parsing of application configuration.
  • email: Logic for sending emails.
  • pdf: Contains the logic for generating PDF documents, acting as a client for a service like Gotenberg.

• /pkg: Contains shared libraries that are okay to be imported by other projects.

  • invoice: The core domain logic for creating and managing invoices. If you are adding business logic related to invoices, it likely belongs here.

Where to Put New Code

• New reusable library: If you are creating a new, self-contained library that could be used by other projects, create a new directory inside /pkg.
• New invoice-related feature: If you are extending the core invoice functionality, add it to the appropriate module within /pkg/invoice.
• New internal logic: For features specific to the API or CLI that are not reusable libraries, add a new module inside /internal.
• New executable: If you are creating a new binary (e.g., a worker or another tool), create a new directory inside /cmd.