tablesguru/looop-reload

Purpose and topology

A Bun monorepo starter for a product with three surfaces: authenticated application, public SEO site, and API. It ships production-grade password authentication, PostgreSQL persistence, shared API contracts, deployment automation, and AI-guided engineering controls. Root commands coordinate the packages via package.json; local infrastructure is defined by docker-compose.yml.

Backend API and lifecycle

The API is a Bun/Hono service. backend/src/index.ts is the HTTP process entry point; backend/src/app.ts assembles routes, middleware, error handling, and application dependencies. backend/src/runtime.ts and backend/src/shutdown.ts define process lifecycle; backend/src/worker.ts supports non-HTTP/background execution. HTTP security and normalized error responses form the external API boundary in backend/src/http/security.ts and backend/src/http/errors.ts.

Auth vertical slice

Authentication is the primary implemented domain module, organized as ports-and-adapters:

• Transport: HTTP routes and authorization middleware in backend/src/modules/auth/transport/routes.ts and backend/src/modules/auth/transport/middleware.ts.

• Application: use-case orchestration and dependency ports in backend/src/modules/auth/application/auth-service.ts and backend/src/modules/auth/application/ports.ts.

• Domain: user/session concepts and domain errors in backend/src/modules/auth/domain/user.ts and backend/src/modules/auth/domain/session.ts.

• Infrastructure: database repository, password hashing, access-token issuance, and rotating refresh-token handling in backend/src/modules/auth/infrastructure/auth-repository.ts, backend/src/modules/auth/infrastructure/passwords.ts, and backend/src/modules/auth/infrastructure/refresh-tokens.ts.

This boundary prevents routes from directly owning persistence or authentication policy.

Persistence, scheduled work, and storage

PostgreSQL is the system of record, accessed through Prisma. Schema and forward migrations live in backend/prisma/schema.prisma and backend/prisma/migrations/; the client boundary is backend/src/db.ts. Session cleanup is separated into scheduled-job logic in backend/src/cron.ts, with VPS systemd timer/service units under scripts/vps/myapp-sessions-cleanup.timer and scripts/vps/myapp-sessions-cleanup.service. File-storage abstraction is centralized in backend/src/storage/service.ts, allowing storage implementation choices to remain outside feature code.

Shared contract boundary

packages/contracts/src/auth.ts contains shared auth request/response validation contracts; packages/contracts/src/errors.ts standardizes error shapes, and packages/contracts/src/index.ts is the package export boundary. Backend transport consumes these contracts, and the web application uses them to keep client/server payload expectations aligned.

Authenticated web application

The logged-in SPA is React/Vite. webapp/src/main.tsx boots the client, while webapp/src/routes.tsx and webapp/src/root-layout.tsx define routing and application shell. Auth state, bootstrapping, browser-tab coordination, and API calls are encapsulated under webapp/src/features/auth/provider.tsx, webapp/src/features/auth/session-coordinator.ts, and webapp/src/features/auth/api.ts. API transport is centralized in webapp/src/platform/api/http-client.ts and webapp/src/platform/api/authenticated-transport.ts, rather than distributed through UI components.

Public site and deployment

The public, indexable surface is a separate Astro application, entered through website/src/pages/index.astro; it should host landing and SEO content rather than authenticated product screens. Deployment targets a self-managed VPS: scripts/vps/deploy.sh installs/releases the backend, scripts/vps/nginx-site.conf.example fronts services with Nginx/HTTPS, and scripts/vps/db-backup.sh supports scheduled PostgreSQL backups. The backend is containerizable via backend/Dockerfile; Docker Compose primarily supplies local database infrastructure.

Governance and quality gates

Architecture boundaries are mechanically checked by scripts/architecture-check.mjs. CI is defined in .github/workflows/ci.yml. Repository-specific agent instructions and iterative plan/code review workflows reside in CLAUDE.md, AGENTS.md, and .claude/skills/.