Developer Guide

Build, extend, and operate uninvoice with confidence

This guide summarizes how the frontend and backend pieces fit together, how to bootstrap the project locally, and which commands keep the codebase healthy. It mirrors the conventions captured in the repository docs.

Overview

uninvoice ships as a balanced mono-repo: the FastAPI backend transforms CSV invoice data into compliant XRechnung/X-Factur PDFs, while the Astro UI helps operators upload files, review generated output, and iterate quickly.

The repository is tuned for container-first workflows using Podman. Outside containers, both services expose lightweight CLIs that keep local development fast without additional dependencies.

Project Structure

The high-level layout mirrors the production architecture. Keep new files aligned with these conventions so test coverage and container builds stay predictable.

Backend

  • backend/app/ FastAPI app, processors, generators, shared schemas.
  • backend/tests/ Pytest suites with golden artifacts.
  • test/ Lightweight integration harness for container smoke tests.

Frontend

  • frontend/src/pages/ Route-driven Astro pages.
  • frontend/src/components/ Reusable UI primitives in PascalCase.
  • frontend/data/ Environment-aware constants.

Local Setup

Backend

  1. Install dependencies with poetry install or uv pip install .
  2. Run the server: poetry run uvicorn app.main:app --reload --port 8000.
  3. Hit http://localhost:8000/docs for the OpenAPI explorer.

Frontend

  1. From frontend/, install dependencies via npm install.
  2. Launch the dev server with npm run dev; it respects the local .env.
  3. Review bundled output using npm run build followed by npm run preview.

Containers

Use the Podman compose stack for parity with CI: make up to start both services, make logs for aggregated logs, and make down to stop.

Development Workflow

Lean on fast feedback loops. Keep backend logic in dedicated modules (e.g. processors/ and generators/), and let Astro pages focus on UI composition and user flows.

  • Expose reusable UI building blocks through src/components/.
  • Share TypeScript helpers via src/lib/ and colocate domain types in src/types.d.ts.
  • Keep environment-aware constants under frontend/data/ rather than hard-coding them.
  • Document API changes in docs/ and update golden fixtures under backend/tests/utils/ when behavior shifts.

Testing

Ship changes with deterministic validation before opening a PR. The backend relies on targeted pytest suites, and the frontend uses linting, type checking, and manual smoke tests.

Backend tests

  • poetry run pytest backend/tests -q for the full suite.
  • Scope with -k when iterating on a scenario.
  • Store generated fixtures beside tests under backend/tests/utils/.

Frontend checks

  • npm run validate for ESLint + TypeScript.
  • npm run format when adjusting styles or layout.
  • Smoke the UI via npm run dev or the Podman stack.

Contributing Notes

Follow the conventional commit style (feat:, fix:, chore:) and keep subjects imperative. Mention relevant issues, outline schema or API changes, and list the validation commands you executed.

When touching PDF generation or CSV ingestion, include sample artifacts (PDF or CSV) in PR descriptions or attach them to docs for reviewers.

Resources