Domus

Digital parish administration. One platform serving many dioceses, organized as diocese → parish → unit (lingkungan).

The monorepo is managed with Bun workspaces and Turborepo.

Repository Structure

domus/
├── apps/
│   ├── auth/          # @domus/auth        - Authentication service (ElysiaJS + Better Auth)
│   ├── api/           # @domus/api         - REST backend (Go, Fiber v3, Ent, Casbin, Swaggo)
│   └── dash/          # @domus/dash        - Web dashboard (React Router v8 SPA, Ant Design)
├── packages/
│   ├── better-auth/   # @domus/better-auth - Better Auth + Drizzle configuration (server & client)
│   ├── openapi/       # @domus/openapi     - TypeScript types generated from the `apps/api` OpenAPI spec
│   └── tsconfig/      # @domus/tsconfig    - Shared base tsconfig
├── e2e/               # @domus/e2e         - End-to-end tests (Cucumber + Playwright)
├── .devcontainer/     # Full dev environment (tools + Postgres, Redis, RustFS, Kafka)
├── .github/           # CI, image builds, release-please, Renovate
├── BRANDING.md        # Dashboard visual guidelines / design tokens
└── turbo.json

Package	Description	Port
apps/auth	Login, sessions, and JWT issuer (Better Auth admin + jwt plugins). Optional Google/GitHub social login.	8001
apps/api	REST backend. Verifies JWTs via the JWKS from apps/auth, Ent ORM, Casbin authorization, OpenAPI v3.1 spec via Swaggo.	8002
apps/dash	SPA dashboard (ssr: false) with a module launcher and i18n (id/en).	3001
packages/better-auth	Better Auth instance, Drizzle schema (Postgres schema auth), zod-validated env.	-
packages/openapi	src/api.ts generated by openapi-typescript, consumed by openapi-fetch in the dashboard.	-

Architecture

 Browser ──► apps/dash ──(login)──► apps/auth ──► Postgres (schema `auth`)
     │                                  │
     │  Bearer JWT                      │ JWKS
     └────────────► apps/api ◄──────────┘
                       │
                       └──► Postgres (Ent)

• apps/auth issues JWTs. apps/api verifies them with the JWKS, matches iss/aud against AUTH_URL, and creates a local user snapshot on the first request.
• Authorization in apps/api is membership based per scope (system, diocese, parish, unit), with per-module roles (e.g. finance-writer) and a global superadmin.
• The dashboard uses a module registry (sys, web, sacra, fin, par, act). Adding a module means adding one entry to apps/dash/app/shared/modules/registry.ts.

Tech Stack

• Backend: Go, Fiber v3, Ent, Casbin, Swaggo
• Auth: ElysiaJS, Better Auth, Drizzle ORM
• Frontend: React 19, React Router v8 (SPA), Ant Design 6, Tailwind CSS 4, i18next
• Data / infra (devcontainer & CI): PostgreSQL 18, Redis 8, RustFS (S3-compatible), Apache Kafka (KRaft)
• Tooling: Bun, Turborepo, Biome, Husky + Commitlint, Air, Swag, Vitest, Cucumber, Playwright

Redis, S3 (RustFS), and Kafka are currently only provisioned in the devcontainer and CI; no application code uses them yet.

Prerequisites

• Bun 1.4.2 and Node.js >= 22
• Go 1.27 (see apps/api/go.mod)
• Docker & Docker Compose (Postgres and supporting services)
• Go tools: air and swag v2

Easiest path: open the repo in the devcontainer (or GitHub Codespaces). All tools, services, and environment variables are prepared, and bun install and bun db:push run automatically.

Getting Started

git clone https://github.com/kilip/domus.git
cd domus

bun install            # also installs git hooks (husky)
bun run db:push        # sync the Better Auth schema to Postgres

bun run dev            # run all apps (turbo)

Run a single app:

bunx turbo run dev --filter=@domus/auth
bunx turbo run dev --filter=@domus/api
bunx turbo run dev --filter=@domus/dash

Once running: dashboard at http://localhost:3001, auth at http://localhost:8001 (OpenAPI docs at /openapi), API at http://localhost:8002.

Environment

In the devcontainer all values below are set through .devcontainer/compose.yaml. Outside the devcontainer, create a .env (git-ignored; apps/api also reads .env via godotenv).

Variable	Used by	Notes
AUTH_URL	auth, api, e2e	Public auth URL (also the JWT iss/aud)
AUTH_HOST, AUTH_PORT	auth	Optional; default derived from AUTH_URL (port 8001)
AUTH_PATH	auth	Better Auth base path (dev: empty)
AUTH_DB_URL	auth, better-auth	Postgres connection for Better Auth
AUTH_SECRET	auth	Better Auth secret (change in production)
AUTH_TRUSTED_ORIGINS	auth, api	Comma-separated CORS origins
AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET	auth	Optional, Google login
AUTH_GITHUB_ID / AUTH_GITHUB_SECRET	auth	Optional, GitHub login
AUTH_JWKS_URL	api	JWKS endpoint of the auth service. Not set in compose/CI yet, set it manually
API_DB_URL	api	Postgres connection for the API (...?sslmode=disable locally)
API_PORT	api	Defaults to 8002
VITE_AUTH_URL, VITE_PUBLIC_URL	dash	Auth URL and public dashboard URL
VITE_API_URL	dash	Defaults to http://localhost:8002
REDIS_URL, S3_*, KAFKA_BROKERS	-	Provisioned for infra, not used by code yet

OpenAPI & Types

The OpenAPI v3.1 spec is generated from the Swaggo annotations in apps/api, then converted to TypeScript types in packages/openapi:

bun run api:gen
# = turbo run oa:gen (swag init in apps/api)
#   + openapi-typescript apps/api/docs/swagger.json -> packages/openapi/src/api.ts

Commit the results (apps/api/docs/* and packages/openapi/src/api.ts) whenever annotations or response models change.

Common Commands

bun run dev          # all apps, watch mode
bun run build        # build packages/apps that define a build script
bun run typecheck    # TypeScript typecheck
bun run lint         # Biome check (lint + format)
bun run lint:fix     # Biome auto-fix
bun run test         # tests via turbo (see note below)
bun run e2e          # end-to-end tests
bun run db:push      # sync the Better Auth schema to the DB (dev)

Testing

• API (Go): cd apps/api && go test ./.... API tests are not part of bun run test because apps/api has no test script; CI runs them directly.
• Better Auth: bun --filter @domus/better-auth test (Vitest).
• E2E: bun run e2e. The runner starts auth, dash, and api automatically if they are not already running (disable with E2E_AUTO_START=false). Add HEADED=true to watch the browser. Run bunx playwright install chromium once beforehand.

Docker

All images are built from the repo root (context .):

docker build -f apps/api/Dockerfile  -t domus-api .
docker build -f apps/auth/Dockerfile -t domus-auth .
docker build -f apps/dash/Dockerfile -t domus-dash .
docker build -f Dockerfile.migrator  -t domus-migrator .   # one-shot job: db:push for the Better Auth schema

The build.yml workflow pushes images to ghcr.io/<owner>/domus/<app> (nightly/sha-* tags for pushes to main, semver + latest for releases).

Contributing

1. Branch off main.
2. Commit using Conventional Commits. Allowed scopes: auth, dash, api, e2e, deps, ci, release, tools (validated by commitlint).
3. The pre-commit hook runs biome check --staged; make sure bun run lint and the relevant tests pass.
4. Open a pull request against main. CI runs the API tests, Better Auth tests, and E2E.

Releases and CHANGELOG.md are managed automatically by release-please from commits on main.

Guidance for AI coding agents is in AGENTS.md; dashboard visual guidelines are in BRANDING.md.

License

MIT © Paroki Developer