-
Notifications
You must be signed in to change notification settings - Fork 0
architecture
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.
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 |
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
- 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.nodomain and the Dokploy environment variables are configured in Cloudflare and Dokploy, not in any repository.
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
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
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.
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"
users ||--o{ lending_requests: "lender"
users ||--o{ lending_requests: "borrower"
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"
timestamptz created_at
}
The API applies the migrations in migrations/ when it starts. Deleting a user cascades to
their uploads and items. The foreign keys on lending_requests have no delete rule, so a
referenced item or user can't be deleted.