Skip to content

Architecture

The system is one Go program (package main, module github.com/nazimbistamamsiru/network-business-system) that renders HTML on the server. It uses no web framework and no JavaScript build step.

Layout

  • main.go: template functions, render(), the login and signup handlers, and route registration on a net/http ServeMux.
  • One file per area (contacts.go, items.go, journals.go, payroll.go, crm_deals.go, …). Each file has the area's HTTP handlers first, then its Store methods, SQL and types under a // ---------- <Area> ---------- marker.
  • db.go: the Store, which wraps a pgxpool.Pool. Every query method takes a context.Context first.
  • schema.sql: the whole schema and its migrations, written so they can be run again (CREATE TABLE IF NOT EXISTS, ADD COLUMN IF NOT EXISTS). There's no migration tool, so add changes to the end of the file.
  • templates/: each file defines one template by its file name. navbar.html holds the shared page shell, styles and scripts.
  • locales/: translations keyed by their English text.
  • packages.go: the list of packages (Core, extensions, modules) and what each owns: its URL paths, pages, permissions and journal types.

A request's path

  1. withSession looks up the session cookie.
  2. withPackages answers "not found" for the paths of a package that's switched off.
  3. withActivityLog records each POST.
  4. The route's guards run: pageGuard (the page is switched on), requirePermission or adminOnly, accessGuard (record scope, field rules, limits), and approvalGate (the entry may need a verifier or approver first).
  5. The handler runs. A POST redirects back with ?success= or ?error=, and a GET calls render().

Conventions

  • Post, then redirect, then get. Errors go back to the page as ?error=.
  • Every logged-in route is registered through pageRoutes, which adds the guards.
  • Pages use the shared components and colour tokens in navbar.html and base-styles.html. go run ./tools/uicheck lists template lines that skip them.

CLAUDE.md in the repository root describes every area in detail.