Development¶

Development environment¶

Requirement	Notes
Go 1.22+	`go.mod`
Sibling `../shared`	Required local module
Optional PostgreSQL	Needed for auth/portal/admin work
Browser	Portal UI uses CDN Materialize/Fonts

Suggested setup:

cd central
export CENTRAL_DATABASE_URL='postgres://USER:PASSWORD@127.0.0.1:5432/acugis_meta?sslmode=disable'
export CENTRAL_ADMIN_USERNAME=admin
export CENTRAL_ADMIN_PASSWORD='dev-password'
go run .

Open http://127.0.0.1:8888/.

Project layout¶

See Architecture for package responsibilities. Practically:

Add routes near the mux registrations in main.go
Put domain SQL under internal/portal/
Put HTML/JS under web/
Prefer shared/auth abstractions instead of re-implementing session hashing

Coding standards¶

No project-local lint config, formatter config, or contribution guide was found under central/. Observed conventions in source:

Standard Go formatting (gofmt)
Package-level comments on main
JSON error envelope {"error":"..."}
Prefer DisallowUnknownFields for admin/card JSON
Keep HTML templates in web/ and pass BasePath

Running tests¶

Existing tests found:

File	Focus
`internal/portal/catalog_test.go`	Catalog aggregation helpers
`internal/portal/thumbnails_test.go`	Thumbnail validation/storage

Run:

cd central
go test ./...

There are no end-to-end HTTP or database integration tests in this directory.

Debugging¶

Technique	Detail
Process logs	stdout via `log.Printf`; look for `central:` prefixes
systemd journal	`journalctl -u central -f`
Health	`curl localhost:8888/api/health`
Auth state	`curl -b jar localhost:8888/api/me`
Discovery	Catalog warnings in `/api/catalog`; admin resource discovery returns `502` with body text
Proxy headers	Confirm `X-Forwarded-Proto` / `Host` when debugging Secure cookies and discovery origins

Useful local overrides: CENTRAL_LISTEN, CENTRAL_WEB_ROOT, CENTRAL_CATALOG_CACHE_TTL, BASE_PATH.

Logging¶

Central uses the Go standard log package only. Notable messages include login outcomes, discovery cookie headers, schema/bootstrap status, and generated admin passwords. No log levels or structured fields are implemented.

Adding new endpoints¶

Implement a handler method on app or a pure handler in the main package.
Register an explicit method+path on the mux (GET /api/...).
If the route should honor BASE_PATH, wrap with mount(...).
Decide auth gate: none, requireAuthenticatedUser, or requireAdmin.
Document the route in docs/api.md and docs/openapi.yaml.
If the UI needs it, add a client call under web/*.js.

For admin identity entities already backed by shared/auth providers, extend admin_auth.go rather than opening ad-hoc SQL in handlers.

Adding new database tables¶

Add CREATE TABLE IF NOT EXISTS ... (and any indexes) to PostgresStore.EnsureSchema in internal/portal/store.go.
Mirror important additive ALTERs for existing deployments.
Update DTOs and scanners.
Document the table in docs/database.md.
Remember there is no versioned migrator; keep statements idempotent.

Also update deploy/sql/ only if you intentionally maintain a standalone SQL artifact (today it covers cards only).

Release process¶

No Central-specific release automation, version tag scheme, changelog history, or packaging pipeline was found in this directory. Practically used build commands:

./build.sh        # Linux/macOS binary named central
.\build.ps1       # Windows central.exe

Deploy by installing the binary and web/ to /opt/central, refreshing /etc/central.env, and restarting systemd (systemctl restart central). Parent-repo git history includes Central changes under commit subjects such as PATS, navigation, and login page work, but those subjects are not a formal SemVer history for this service.

This documentation set therefore initializes the public changelog baseline at 1.0.0 in changelog.md.