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

Writing Tests

All tests are written using the go standard library and are table driven. In this application no libraries like testify are used. Mocks are written in the test file using this schema:

type Mock struct {
	Foo func (string) string
}

func (m Mock) Foo(in string) string {
	return m.Foo(in)
}

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.