Overview

Homebox is a complex application with a lot of moving parts. This page will give you an overview of the backend codebase structure to help you get started with development. We hope that this document will help you understand the architecture of the backend and help you get started with development.

Task Commands To Know

There are several invaluable Task commands that you’ll need to know to get started with development. A few of them you’ll need to run everytime before submitting a PR.

• task generate - generates OpenAPI docs and JS types (run this EVERY time before submitting a PR)
• task go:lint - runs linters (run this EVERY time before submitting a PR)
• task go:run - runs the backend server locally with sqlite
• task go:run:postgres - runs the backend server locally with postgres
• task go:test - runs backend tests

File Structure

• Directorybackend

  • Directoryapp

    • Directoryapi

      • Directoryhandlers contains request handlers

        • …
      • Directoryproviders contains a couple special handlers for docs, OIDC, etc.

        • …
      • Directorystatic frontend stuff (auto-gen)

        • …
      • app.go
      • bgrunner.go tasks that run in background
      • demo.go demo related code
      • logger.go zero logger config
      • main.go primary app startup
      • middleware.go HTTP middleware
      • recurring.go constant running tasks
      • routes.go HTTP routes definitions
      • setup.go setup functions
    • Directorytools

      • …
  • Directoryinternal

    • Directorycore

      • Directorycurrencies

        • …
      • Directoryservices

        • …
    • Directorydata

      • Directoryent

        • Directoryschema definition of ORM schema

          • user.go
          • …
        • … the rest is auto-gen
      • Directorymigrations goose migrations (both required)

        • Directorypostgres

          • 20220929052825_init.sql
          • 20241226183416_sync_children.go
          • …
        • Directorysqlite3

          • 20220929052825_init.sql
          • 20241226183416_sync_children.go
          • …
      • Directoryrepo contains actual database interaction logic

        • repo_users.go
        • repo_users_test.go
        • …
      • Directorytypes special defined types

        • date.go
  • Directorypkgs contains internal packages

    • Directoryhasher

      • password.go
      • …
    • …
  • .goreleaser.yaml
  • go.mod
  • go.sum

Architecture & Implementation

For detailed guides on specific backend components, see:

• API Handlers – How HTTP requests are processed
• Data Layer & Ent - Database and ORM usage