# tablesguru/looop-reload architecture

> Architecture diagram of the GitHub repository tablesguru/looop-reload, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tablesguru/looop-reload
- Repository: https://github.com/tablesguru/looop-reload

## Overview

#### 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/`.

Main entry points: [`backend/src/modules/auth/transport/routes.ts`](https://github.com/tablesguru/looop-reload/blob/main/backend/src/modules/auth/transport/routes.ts) (Auth transport), [`backend/src/modules/auth/application/auth-service.ts`](https://github.com/tablesguru/looop-reload/blob/main/backend/src/modules/auth/application/auth-service.ts) (Auth use cases), [`webapp/src/features/auth/provider.tsx`](https://github.com/tablesguru/looop-reload/blob/main/webapp/src/features/auth/provider.tsx) (Web auth client), [`backend/src/index.ts`](https://github.com/tablesguru/looop-reload/blob/main/backend/src/index.ts) (HTTP process)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend API"]
  node_api_entry["HTTP process<br/>Bun/Hono entry<br/>[index.ts]"]
  node_api_app["API assembly<br/>Hono app<br/>[app.ts]"]
  node_api_boundary["HTTP boundary<br/>security and errors<br/>[security.ts]"]
  node_auth_transport["Auth transport<br/>routes and middleware<br/>[routes.ts]"]
  node_auth_application["Auth use cases<br/>application service<br/>[auth-service.ts]"]
  node_auth_domain["Auth domain<br/>user and session model<br/>[user.ts]"]
  node_auth_infrastructure["Auth adapters<br/>repository and tokens<br/>[auth-repository.ts]"]
  node_worker_runtime["Worker lifecycle<br/>background runtime<br/>[worker.ts]"]
end

subgraph group_clients["Client Surfaces"]
  node_webapp["Authenticated SPA<br/>React/Vite client<br/>[main.tsx]"]
  node_web_auth["Web auth client<br/>auth state and API<br/>[provider.tsx]"]
  node_website["Public SEO site<br/>Astro application<br/>[index.astro]"]
end

subgraph group_platform["Data &amp; Operations"]
  node_prisma["Prisma data model<br/>schema and migrations<br/>[schema.prisma]"]
  node_postgres[("PostgreSQL<br/>system of record")]
  node_local_infra["Local infrastructure<br/>Docker Compose<br/>[docker-compose.yml]"]
  node_scheduled_cleanup["Session cleanup<br/>scheduled job<br/>[cron.ts]"]
  node_deployment["VPS deployment<br/>release automation<br/>[deploy.sh]"]
end

node_root_commands["Monorepo commands<br/>workspace coordinator<br/>[package.json]"]
node_contracts["Shared contracts<br/>validation package<br/>[index.ts]"]
node_quality_gates["Quality gates<br/>architecture and CI"]

node_root_commands -->|"runs"| node_api_entry
node_root_commands -->|"runs"| node_webapp
node_api_entry -->|"starts"| node_api_app
node_api_app -->|"applies"| node_api_boundary
node_api_boundary -->|"protects"| node_auth_transport
node_auth_transport -->|"invokes"| node_auth_application
node_auth_application -->|"uses"| node_auth_domain
node_auth_application -->|"uses ports through"| node_auth_infrastructure
node_auth_infrastructure -->|"persists users and sessions"| node_postgres
node_prisma -->|"models"| node_postgres
node_local_infra -->|"provisions locally"| node_postgres
node_scheduled_cleanup -->|"removes expired sessions"| node_postgres
node_worker_runtime -.->|"can execute"| node_scheduled_cleanup
node_auth_transport -->|"validates with"| node_contracts
node_webapp -->|"hosts"| node_web_auth
node_web_auth -->|"uses payload contracts"| node_contracts
node_web_auth -->|"calls API"| node_api_boundary
node_deployment -->|"releases"| node_api_entry
node_quality_gates -.->|"checks boundaries"| node_api_app

click node_root_commands "https://github.com/tablesguru/looop-reload/blob/main/package.json"
click node_api_entry "https://github.com/tablesguru/looop-reload/blob/main/backend/src/index.ts"
click node_api_app "https://github.com/tablesguru/looop-reload/blob/main/backend/src/app.ts"
click node_api_boundary "https://github.com/tablesguru/looop-reload/blob/main/backend/src/http/security.ts"
click node_auth_transport "https://github.com/tablesguru/looop-reload/blob/main/backend/src/modules/auth/transport/routes.ts"
click node_auth_application "https://github.com/tablesguru/looop-reload/blob/main/backend/src/modules/auth/application/auth-service.ts"
click node_auth_domain "https://github.com/tablesguru/looop-reload/blob/main/backend/src/modules/auth/domain/user.ts"
click node_auth_infrastructure "https://github.com/tablesguru/looop-reload/blob/main/backend/src/modules/auth/infrastructure/auth-repository.ts"
click node_worker_runtime "https://github.com/tablesguru/looop-reload/blob/main/backend/src/worker.ts"
click node_contracts "https://github.com/tablesguru/looop-reload/blob/main/packages/contracts/src/index.ts"
click node_webapp "https://github.com/tablesguru/looop-reload/blob/main/webapp/src/main.tsx"
click node_web_auth "https://github.com/tablesguru/looop-reload/blob/main/webapp/src/features/auth/provider.tsx"
click node_website "https://github.com/tablesguru/looop-reload/blob/main/website/src/pages/index.astro"
click node_prisma "https://github.com/tablesguru/looop-reload/blob/main/backend/prisma/schema.prisma"
click node_local_infra "https://github.com/tablesguru/looop-reload/blob/main/docker-compose.yml"
click node_scheduled_cleanup "https://github.com/tablesguru/looop-reload/blob/main/backend/src/cron.ts"
click node_deployment "https://github.com/tablesguru/looop-reload/blob/main/scripts/vps/deploy.sh"
click node_quality_gates "https://github.com/tablesguru/looop-reload/blob/main/scripts/architecture-check.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_entry,node_api_app,node_api_boundary,node_auth_transport,node_auth_application,node_auth_domain,node_auth_infrastructure,node_worker_runtime toneBlue
class node_webapp,node_web_auth,node_website toneAmber
class node_prisma,node_postgres,node_local_infra,node_scheduled_cleanup,node_deployment toneMint
class node_root_commands,node_contracts,node_quality_gates toneNeutral
```

## Components

### Backend API

Bun/Hono service and auth vertical slice.

- [HTTP process](https://github.com/tablesguru/looop-reload/blob/main/backend/src/index.ts): Bun/Hono entry · Starts the API runtime. · `backend/src/index.ts`
- [API assembly](https://github.com/tablesguru/looop-reload/blob/main/backend/src/app.ts): Hono app · Composes routes, middleware, errors, and dependencies. · `backend/src/app.ts`
- [HTTP boundary](https://github.com/tablesguru/looop-reload/blob/main/backend/src/http/security.ts): security and errors · Applies HTTP security and normalized errors. · `backend/src/http/security.ts`
- [Auth transport](https://github.com/tablesguru/looop-reload/blob/main/backend/src/modules/auth/transport/routes.ts): routes and middleware · Exposes auth endpoints and authorization checks. · `backend/src/modules/auth/transport/routes.ts`
- [Auth use cases](https://github.com/tablesguru/looop-reload/blob/main/backend/src/modules/auth/application/auth-service.ts): application service · Orchestrates auth policy through dependency ports. · `backend/src/modules/auth/application/auth-service.ts`
- [Auth domain](https://github.com/tablesguru/looop-reload/blob/main/backend/src/modules/auth/domain/user.ts): user and session model · Defines user, session, and domain-error concepts. · `backend/src/modules/auth/domain/user.ts`
- [Auth adapters](https://github.com/tablesguru/looop-reload/blob/main/backend/src/modules/auth/infrastructure/auth-repository.ts): repository and tokens · Implements persistence, passwords, access tokens, and rotating refresh tokens. · `backend/src/modules/auth/infrastructure/auth-repository.ts`
- [Worker lifecycle](https://github.com/tablesguru/looop-reload/blob/main/backend/src/worker.ts): background runtime · Supports non-HTTP execution and graceful shutdown. · `backend/src/worker.ts`

### Client Surfaces

Separate authenticated app and public site.

- [Authenticated SPA](https://github.com/tablesguru/looop-reload/blob/main/webapp/src/main.tsx): React/Vite client · Boots routes and application shell. · `webapp/src/main.tsx`
- [Web auth client](https://github.com/tablesguru/looop-reload/blob/main/webapp/src/features/auth/provider.tsx): auth state and API · Coordinates sessions and authenticated API calls. · `webapp/src/features/auth/provider.tsx`
- [Public SEO site](https://github.com/tablesguru/looop-reload/blob/main/website/src/pages/index.astro): Astro application · Hosts landing and indexable content. · `website/src/pages/index.astro`

### Data & Operations

Persistence, local infrastructure, deployment, and automation.

- [Prisma data model](https://github.com/tablesguru/looop-reload/blob/main/backend/prisma/schema.prisma): schema and migrations · Defines PostgreSQL schema and forward migrations. · `backend/prisma/schema.prisma`
- **PostgreSQL**: system of record
- [Local infrastructure](https://github.com/tablesguru/looop-reload/blob/main/docker-compose.yml): Docker Compose · Primarily provides local database infrastructure. · `docker-compose.yml`
- [Session cleanup](https://github.com/tablesguru/looop-reload/blob/main/backend/src/cron.ts): scheduled job · Cleanup logic run by VPS systemd timer/service units. · `backend/src/cron.ts`
- [VPS deployment](https://github.com/tablesguru/looop-reload/blob/main/scripts/vps/deploy.sh): release automation · Deploys backend behind Nginx and supports database backups. · `scripts/vps/deploy.sh`

### Other components

- [Monorepo commands](https://github.com/tablesguru/looop-reload/blob/main/package.json): workspace coordinator · Coordinates package-level commands. · `package.json`
- [Shared contracts](https://github.com/tablesguru/looop-reload/blob/main/packages/contracts/src/index.ts): validation package · Auth payload and standardized error contract boundary. · `packages/contracts/src/index.ts`
- [Quality gates](https://github.com/tablesguru/looop-reload/blob/main/scripts/architecture-check.mjs): architecture and CI · Mechanically checks boundaries in CI. · `scripts/architecture-check.mjs`

## Connections

- Monorepo commands → HTTP process: runs
- Monorepo commands → Authenticated SPA: runs
- HTTP process → API assembly: starts
- API assembly → HTTP boundary: applies
- HTTP boundary → Auth transport: protects
- Auth transport → Auth use cases: invokes
- Auth use cases → Auth domain: uses
- Auth use cases → Auth adapters: uses ports through
- Auth adapters → PostgreSQL: persists users and sessions
- Prisma data model → PostgreSQL: models
- Local infrastructure → PostgreSQL: provisions locally
- Session cleanup → PostgreSQL: removes expired sessions
- Worker lifecycle → Session cleanup: can execute
- Auth transport → Shared contracts: validates with
- Authenticated SPA → Web auth client: hosts
- Web auth client → Shared contracts: uses payload contracts
- Web auth client → HTTP boundary: calls API
- VPS deployment → HTTP process: releases
- Quality gates → API assembly: checks boundaries