# bkabondo/timelock architecture

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

- Interactive diagram: https://gitdiagram.com/bkabondo/timelock
- Repository: https://github.com/bkabondo/timelock

## Overview

TimeLock lets users seal encrypted messages for a future unlock date, then revisit or share links to reveal them. The main workflow is browser-side encryption, capsule and content storage (either signed-in or guest), and later token/key-based retrieval and decryption. The tree also shows authentication, public capsule browsing, admin activity views, and an email-sharing module. Several page and integration implementations were not sampled, so uncertain internal wiring is omitted; documented guest-token and fragment behavior is retained.

Main entry points: [`lib/supabase/server.ts`](https://github.com/bkabondo/timelock/blob/main/lib/supabase/server.ts) (Server database client), [`app/capsules/new/page.tsx`](https://github.com/bkabondo/timelock/blob/main/app/capsules/new/page.tsx) (Create capsule), [`lib/supabase/admin.ts`](https://github.com/bkabondo/timelock/blob/main/lib/supabase/admin.ts) (Admin database client), [`app/capsules/[id]/page.tsx`](https://github.com/bkabondo/timelock/blob/main/app/capsules/%5Bid%5D/page.tsx) (Capsule detail)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creation["Capsule creation"]
  node_newcapsule["Create capsule<br/>[page.tsx]"]
  node_crypto["Browser encryption<br/>[capsule-crypto.ts]"]
  node_guestapi["Guest capsule API<br/>[route.ts]"]
end

subgraph group_access["Capsule access"]
  node_listing["Capsule listing<br/>[page.tsx]"]
  node_detail["Capsule detail<br/>[page.tsx]"]
  node_guestloader["Guest capsule loader"]
  node_capsuleview["Capsule view<br/>[CapsuleView.tsx]"]
  node_reveal["Letter reveal<br/>[LetterReveal.tsx]"]
  node_fragment["Link fragment parser"]
  node_tokenclient["Token database client<br/>[token-client.ts]"]
  node_countdown["Unlock countdown<br/>[Countdown.tsx]"]
  node_emailshare["Email sharing<br/>[share.py]"]
end

subgraph group_identity["Identity and admin"]
  node_login["Login<br/>[page.tsx]"]
  node_signup["Sign up<br/>[page.tsx]"]
  node_callback["Auth callback<br/>[route.ts]"]
  node_profile["Create profile API<br/>[route.ts]"]
  node_adminpage["Admin dashboard<br/>[page.tsx]"]
  node_seed["Seed admin API<br/>[route.ts]"]
end

subgraph group_services["Data and services"]
  node_browserclient["Browser database client<br/>[client.ts]"]
  node_serverclient["Server database client<br/>[server.ts]"]
  node_adminclient["Admin database client<br/>[admin.ts]"]
  node_database[("Supabase database and auth")]
  node_ratelimit["Rate limiter<br/>[rate-limit.ts]"]
end

node_visitor(("Visitor"))
node_signedin(("Signed-in user"))

node_visitor -->|"creates"| node_newcapsule
node_signedin -->|"creates"| node_newcapsule
node_newcapsule -->|"encrypts locally"| node_crypto
node_newcapsule -->|"writes signed-in capsule"| node_browserclient
node_newcapsule -->|"posts guest capsule"| node_guestapi
node_guestapi -->|"checks limit"| node_ratelimit
node_guestapi -->|"stores guest capsule"| node_adminclient
node_browserclient -->|"reads and writes"| node_database
node_serverclient -->|"reads and writes"| node_database
node_adminclient -->|"privileged access"| node_database
node_signedin -->|"views capsules"| node_listing
node_visitor -->|"opens link"| node_detail
node_signedin -->|"opens capsule"| node_detail
node_detail -->|"loads guest capsule"| node_guestloader
node_guestloader -->|"reads link secrets"| node_fragment
node_guestloader -->|"requests token access"| node_tokenclient
node_tokenclient -->|"reads under RLS"| node_database
node_detail -->|"renders capsule"| node_capsuleview
node_capsuleview -->|"presents letter"| node_reveal
node_reveal -->|"decrypts locally"| node_crypto
node_capsuleview -->|"shows unlock time"| node_countdown
node_signedin -->|"authenticates"| node_login
node_visitor -->|"registers"| node_signup
node_login -->|"uses auth session"| node_serverclient
node_signup -->|"uses auth session"| node_serverclient
node_callback -->|"exchanges auth code"| node_serverclient
node_profile -->|"checks session"| node_serverclient
node_profile -->|"creates profile"| node_adminclient
node_adminpage -->|"checks identity"| node_serverclient
node_adminpage -->|"queries activity"| node_adminclient
node_seed -->|"seeds admin account"| node_adminclient
node_emailshare -.->|"shares capsule by email"| node_visitor

click node_newcapsule "https://github.com/bkabondo/timelock/blob/main/app/capsules/new/page.tsx"
click node_crypto "https://github.com/bkabondo/timelock/blob/main/lib/capsule-crypto.ts"
click node_guestapi "https://github.com/bkabondo/timelock/blob/main/app/api/capsules/guest/route.ts"
click node_listing "https://github.com/bkabondo/timelock/blob/main/app/capsules/page.tsx"
click node_detail "https://github.com/bkabondo/timelock/blob/main/app/capsules/%5Bid%5D/page.tsx"
click node_guestloader "https://github.com/bkabondo/timelock/blob/main/app/capsules/%5Bid%5D/GuestCapsuleLoader.tsx"
click node_capsuleview "https://github.com/bkabondo/timelock/blob/main/app/capsules/%5Bid%5D/CapsuleView.tsx"
click node_reveal "https://github.com/bkabondo/timelock/blob/main/app/capsules/%5Bid%5D/LetterReveal.tsx"
click node_fragment "https://github.com/bkabondo/timelock/blob/main/lib/capsule-fragment.ts"
click node_tokenclient "https://github.com/bkabondo/timelock/blob/main/lib/supabase/token-client.ts"
click node_countdown "https://github.com/bkabondo/timelock/blob/main/components/Countdown.tsx"
click node_emailshare "https://github.com/bkabondo/timelock/blob/main/api/email/share.py"
click node_login "https://github.com/bkabondo/timelock/blob/main/app/login/page.tsx"
click node_signup "https://github.com/bkabondo/timelock/blob/main/app/signup/page.tsx"
click node_callback "https://github.com/bkabondo/timelock/blob/main/app/auth/callback/route.ts"
click node_profile "https://github.com/bkabondo/timelock/blob/main/app/api/auth/create-profile/route.ts"
click node_adminpage "https://github.com/bkabondo/timelock/blob/main/app/admin/page.tsx"
click node_seed "https://github.com/bkabondo/timelock/blob/main/app/api/seed/route.ts"
click node_browserclient "https://github.com/bkabondo/timelock/blob/main/lib/supabase/client.ts"
click node_serverclient "https://github.com/bkabondo/timelock/blob/main/lib/supabase/server.ts"
click node_adminclient "https://github.com/bkabondo/timelock/blob/main/lib/supabase/admin.ts"
click node_ratelimit "https://github.com/bkabondo/timelock/blob/main/lib/rate-limit.ts"

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_newcapsule,node_crypto,node_guestapi,node_signedin toneBlue
class node_listing,node_detail,node_guestloader,node_capsuleview,node_reveal,node_fragment,node_tokenclient,node_countdown,node_emailshare toneAmber
class node_login,node_signup,node_callback,node_profile,node_adminpage,node_seed toneMint
class node_browserclient,node_serverclient,node_adminclient,node_database,node_ratelimit toneRose
class node_visitor toneIndigo
```

## Components

### Capsule creation

- [Create capsule](https://github.com/bkabondo/timelock/blob/main/app/capsules/new/page.tsx): `app/capsules/new/page.tsx`
- [Browser encryption](https://github.com/bkabondo/timelock/blob/main/lib/capsule-crypto.ts): `lib/capsule-crypto.ts`
- [Guest capsule API](https://github.com/bkabondo/timelock/blob/main/app/api/capsules/guest/route.ts): `app/api/capsules/guest/route.ts`

### Capsule access

- [Capsule listing](https://github.com/bkabondo/timelock/blob/main/app/capsules/page.tsx): `app/capsules/page.tsx`
- [Capsule detail](https://github.com/bkabondo/timelock/blob/main/app/capsules/%5Bid%5D/page.tsx): `app/capsules/[id]/page.tsx`
- [Guest capsule loader](https://github.com/bkabondo/timelock/blob/main/app/capsules/%5Bid%5D/GuestCapsuleLoader.tsx): `app/capsules/[id]/GuestCapsuleLoader.tsx`
- [Capsule view](https://github.com/bkabondo/timelock/blob/main/app/capsules/%5Bid%5D/CapsuleView.tsx): `app/capsules/[id]/CapsuleView.tsx`
- [Letter reveal](https://github.com/bkabondo/timelock/blob/main/app/capsules/%5Bid%5D/LetterReveal.tsx): `app/capsules/[id]/LetterReveal.tsx`
- [Link fragment parser](https://github.com/bkabondo/timelock/blob/main/lib/capsule-fragment.ts): `lib/capsule-fragment.ts`
- [Token database client](https://github.com/bkabondo/timelock/blob/main/lib/supabase/token-client.ts): `lib/supabase/token-client.ts`
- [Unlock countdown](https://github.com/bkabondo/timelock/blob/main/components/Countdown.tsx): `components/Countdown.tsx`
- [Email sharing](https://github.com/bkabondo/timelock/blob/main/api/email/share.py): `api/email/share.py`

### Identity and admin

- [Login](https://github.com/bkabondo/timelock/blob/main/app/login/page.tsx): `app/login/page.tsx`
- [Sign up](https://github.com/bkabondo/timelock/blob/main/app/signup/page.tsx): `app/signup/page.tsx`
- [Auth callback](https://github.com/bkabondo/timelock/blob/main/app/auth/callback/route.ts): `app/auth/callback/route.ts`
- [Create profile API](https://github.com/bkabondo/timelock/blob/main/app/api/auth/create-profile/route.ts): `app/api/auth/create-profile/route.ts`
- [Admin dashboard](https://github.com/bkabondo/timelock/blob/main/app/admin/page.tsx): `app/admin/page.tsx`
- [Seed admin API](https://github.com/bkabondo/timelock/blob/main/app/api/seed/route.ts): `app/api/seed/route.ts`

### Data and services

- [Browser database client](https://github.com/bkabondo/timelock/blob/main/lib/supabase/client.ts): `lib/supabase/client.ts`
- [Server database client](https://github.com/bkabondo/timelock/blob/main/lib/supabase/server.ts): `lib/supabase/server.ts`
- [Admin database client](https://github.com/bkabondo/timelock/blob/main/lib/supabase/admin.ts): `lib/supabase/admin.ts`
- **Supabase database and auth**
- [Rate limiter](https://github.com/bkabondo/timelock/blob/main/lib/rate-limit.ts): `lib/rate-limit.ts`

### Other components

- **Visitor**
- **Signed-in user**

## Connections

- Visitor → Create capsule: creates
- Signed-in user → Create capsule: creates
- Create capsule → Browser encryption: encrypts locally
- Create capsule → Browser database client: writes signed-in capsule
- Create capsule → Guest capsule API: posts guest capsule
- Guest capsule API → Rate limiter: checks limit
- Guest capsule API → Admin database client: stores guest capsule
- Browser database client → Supabase database and auth: reads and writes
- Server database client → Supabase database and auth: reads and writes
- Admin database client → Supabase database and auth: privileged access
- Signed-in user → Capsule listing: views capsules
- Visitor → Capsule detail: opens link
- Signed-in user → Capsule detail: opens capsule
- Capsule detail → Guest capsule loader: loads guest capsule
- Guest capsule loader → Link fragment parser: reads link secrets
- Guest capsule loader → Token database client: requests token access
- Token database client → Supabase database and auth: reads under RLS
- Capsule detail → Capsule view: renders capsule
- Capsule view → Letter reveal: presents letter
- Letter reveal → Browser encryption: decrypts locally
- Capsule view → Unlock countdown: shows unlock time
- Signed-in user → Login: authenticates
- Visitor → Sign up: registers
- Login → Server database client: uses auth session
- Sign up → Server database client: uses auth session
- Auth callback → Server database client: exchanges auth code
- Create profile API → Server database client: checks session
- Create profile API → Admin database client: creates profile
- Admin dashboard → Server database client: checks identity
- Admin dashboard → Admin database client: queries activity
- Seed admin API → Admin database client: seeds admin account
- Email sharing → Visitor: shares capsule by email