Skip to content

architecture

Nick Heggø edited this page Oct 15, 2026 · 2 revisions

helpinghand-rs

The REST API for HelpingHand, a neighbourhood item-lending app. Built with Rust and axum, stores data in Postgres through sqlx, uses Keycloak for sign-in and Cloudflare R2 for images.

Architecture

HelpingHand is split across four repositories:

Repository Contents
helpinghand-web React single-page app built with Vite and served by nginx
helpinghand-rs This API
auth Keycloak with the HelpingHand login theme and the helpinghand realm
pg_durable Postgres 18 image with the pg_durable extension, used as the app DB

Runtime

flowchart LR
  browser["Browser<br/>React SPA + keycloak-js"]
  tunnel["Cloudflare tunnel<br/>TLS for *.helpinghand.no"]

  subgraph host["NTNU SkyHigh: OpenStack VM running Dokploy"]
    web["helpinghand-web<br/>nginx :80"]
    api["helpinghand-rs<br/>axum :3000"]
    appdb[("App Postgres<br/>pg_durable, helpinghand_db")]
    notify["Notifications<br/>(planned)"]
    subgraph authstack["auth/compose.yaml"]
      realmcfg["realm-config<br/>one-shot job"]
      kc["Keycloak 26.8<br/>realm helpinghand"]
      kcdb[("Keycloak Postgres<br/>postgres:18")]
    end
  end

  subgraph cfsvc["Cloudflare services"]
    r2[("R2 bucket helpinghand-r2<br/>images.helpinghand.no")]
    smtp["Email Service<br/>SMTP :465"]
  end

  browser -->|HTTPS| tunnel
  tunnel -->|helpinghand . no| web
  tunnel -->|" api.helpinghand.no<br/>REST + Bearer token "| api
  tunnel -->|" auth.helpinghand.no<br/>OIDC + PKCE "| kc
  browser ==>|" presigned PUT<br/>GET images "| r2
  api -->|" sqlx, migrates on boot "| appdb
  api -->|" S3 API: presign, HEAD, DELETE "| r2
  api -.->|JWKS| kc
  realmcfg -->|admin API| kc
  kc -->|JDBC| kcdb
  kc -->|" magic link, email code "| smtp
  appdb -.->|" pg_durable cron (planned) "| notify
  notify -.->|" SMTP (planned) "| smtp
  classDef planned stroke-dasharray: 5 5
  class notify planned
Loading
  • Everything runs on one OpenStack VM in NTNU SkyHigh, managed by Dokploy. Cloudflare provides the public HTTPS endpoint through a tunnel.
  • There are two Postgres instances. The API owns the pg_durable database. Keycloak keeps its own stock Postgres inside the auth stack.
  • Image bytes never pass through the API. It signs an upload URL, and the browser PUTs the file straight to R2.
  • The API reads Keycloak's discovery document and signing keys from the public auth.helpinghand.no, so that request goes out through Cloudflare.
  • Planned: cron jobs in pg_durable will trigger notifications, which send email through Cloudflare Email Service over SMTP, the same way Keycloak does.
  • The Cloudflare tunnel, R2 bucket CORS, the images.helpinghand.no domain and the Dokploy environment variables are configured in Cloudflare and Dokploy, not in any repository.

Signing in

Sign-in is passwordless. The API never creates users by itself: after every login the client must call PUT /users/me, which creates or updates the users row from the token claims. Requests that need a users row fail until that call has succeeded.

sequenceDiagram
    participant B as Browser
    participant K as Keycloak
    participant A as helpinghand-rs
    participant P as App Postgres
    B ->> K: authorize (client helpinghand-web, PKCE S256)
    K -->> B: login page: email, then magic link, code or passkey
    K -->> B: redirect back with code
    B ->> K: POST token (code + PKCE verifier)
    K -->> B: access token, 5 min, aud = account
    B ->> A: PUT /users/me with Bearer token
    A ->> K: fetch signing keys (cached)
    A ->> P: upsert users row from sub, email, name
    A -->> B: 204 No Content
    B ->> A: GET /users/me
    A -->> B: profile with avatar URL
Loading

Uploading an image

sequenceDiagram
    participant B as Browser
    participant A as helpinghand-rs
    participant P as App Postgres
    participant R as R2 bucket
    B ->> A: POST /uploads (content_type, size)
    A ->> A: sign PUT URL, valid 10 min
    A ->> P: INSERT uploads row, pending
    A -->> B: 201 id, upload_url, expires_at
    B ->> R: PUT file bytes (size and type are signed)
    B ->> A: POST /uploads/{id}/complete
    A ->> R: HEAD object, check size and type
    A ->> P: set completed_at
    A -->> B: 200 public URL on images.helpinghand.no
    B ->> A: POST /items with image_ids, or PUT /users/me/avatar
Loading

Only JPEG, PNG and WebP files up to 10 MiB are accepted. Object keys are images/{user_id}/{upload_id}. If the stored object doesn't match what was signed, the API deletes it and returns 422.

Data model

erDiagram
    users ||--o{ uploads: "owns (cascade)"
    users }o--o| uploads: "avatar (set null)"
    users ||--o{ items: "owns (cascade)"
    items ||--o{ item_images: "has, max 6 (cascade)"
    uploads ||--o{ item_images: "shown as (cascade)"
    items ||--o{ lending_requests: "requested in (cascade)"
    users ||--o{ lending_requests: "lender"
    users ||--o{ lending_requests: "borrower"
    lending_requests ||--|{ lending_request_events: "history (cascade)"
    users ||--o{ lending_request_events: "actor"

    users {
        uuid id PK "Keycloak sub"
        text email
        text first_name
        text last_name
        uuid avatar_upload_id FK
        timestamptz created_at
        timestamptz updated_at
    }
    uploads {
        uuid id PK
        uuid owner_id FK
        text key "images/user_id/upload_id"
        text content_type
        bigint size
        timestamptz created_at
        timestamptz completed_at "null while pending"
    }
    items {
        uuid id PK
        uuid owner_id FK
        text name
        text description
        text category
        text availability
        int price_per_day
        int deposit
        timestamp created_at
        timestamp updated_at
    }
    item_images {
        uuid item_id PK, FK
        uuid upload_id PK, FK
        int position
        timestamptz created_at
    }
    lending_requests {
        uuid id PK
        uuid item_id FK
        uuid lender_id FK
        uuid borrower_id FK
        date start_date
        date end_date
        text status "pending, approved, rejected, cancelled, returned"
        timestamptz created_at
    }
    lending_request_events {
        uuid id PK
        uuid request_id FK
        text status "the status the request moved to"
        uuid actor_id FK "who set it"
        timestamptz created_at
    }
Loading

The API applies the migrations in migrations/ when it starts. Deleting a user cascades to their uploads and items, and deleting an item cascades to its lending requests and their history. DELETE /items/{id} still refuses with 409 while an approved loan of the item has yet to end. The user foreign keys on lending_requests and lending_request_events have no delete rule, so a user who has asked to borrow someone else's item can't be deleted.

Lending an item

A lending request is the record of a loan: an item is lent out on a date when an approved request covers it. GET /items/{id}/booked-dates lists the approved loans that haven't ended.

stateDiagram-v2
    [*] --> pending: borrower, POST /lending-requests
    pending --> approved: lender, PATCH /lending-requests/{id}
    pending --> rejected: lender, PATCH /lending-requests/{id}
    pending --> rejected: another request for overlapping dates is approved
    pending --> cancelled: borrower, POST /lending-requests/{id}/cancel
    approved --> cancelled: borrower, before the start date
    approved --> returned: lender, POST /lending-requests/{id}/return, from the start date
    rejected --> [*]
    cancelled --> [*]
    returned --> [*]
Loading
  • Dates are inclusive, start today or later, at most 365 days ahead, and span at most 90 days. "Today" is the UTC date.
  • Borrowers can't request their own items or items set to unavailable.
  • Postgres enforces the rules that matter under concurrency: an exclusion constraint (no_overlapping_approved_loans, using btree_gist) refuses two approved loans of one item with overlapping dates, and a partial unique index (one_pending_per_borrower) allows one pending request per borrower per item.
  • Every status change writes a lending_request_events row in the same transaction. GET /lending-requests/{id}/events returns that history, oldest first.
  • returned frees the rest of the loan's dates for new requests.
Clone this wiki locally