# cooldad7777/stamp-system architecture

> Architecture diagram of the GitHub repository cooldad7777/stamp-system, 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/cooldad7777/stamp-system
- Repository: https://github.com/cooldad7777/stamp-system

## Overview

STAMP is an attendance-verification product built around location check-in/out and cryptographically bound proof. The documented user flow leads from a mobile check-in to validator review and compliance reporting; the available tree does not include mobile source, so its runtime wiring cannot be traced. The backend exposes check-in and TSCB verification routes, and includes cryptographic, geohash, database, and blockchain services. The portal has verification, compliance, audit, and settings areas. An independent CLI audits exported records offline. Differential-privacy analytics and federated fraud detection are README capabilities, but no implementation paths for them appear in this tree.

Main entry points: [`validator-portal/src/components/AppRouter.tsx`](https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/components/AppRouter.tsx) (Portal routing), [`backend/src/server.ts`](https://github.com/cooldad7777/stamp-system/blob/main/backend/src/server.ts) (API server), [`backend/src/services/BlockchainVerificationService.ts`](https://github.com/cooldad7777/stamp-system/blob/main/backend/src/services/BlockchainVerificationService.ts) (Cross-jurisdiction verification), [`mobile`](https://github.com/cooldad7777/stamp-system/tree/main/mobile) (Mobile app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_attendance["Attendance proof"]
  node_mobile["Mobile app"]
  node_checkin["Check-in API<br/>[checkin.ts]"]
  node_tscbroute["TSCB verify API<br/>[tscb-verify.ts]"]
end

subgraph group_backend["Backend trust"]
  node_tscb["TSCB protocol<br/>[TSCBProtocol.ts]"]
  node_crypto["Crypto service<br/>[CryptoService.ts]"]
  node_geohash["Geohash service<br/>[GeohashService.ts]"]
  node_server["API server<br/>[server.ts]"]
  node_database["Database service<br/>[DatabaseService.ts]"]
  node_db[("PostgreSQL")]
  node_blockchain["Cross-jurisdiction verification"]
end

subgraph group_portal["Validator portal"]
  node_portal["Portal app<br/>[App.tsx]"]
  node_router["Portal routing<br/>[AppRouter.tsx]"]
  node_auth["Auth state<br/>[AuthStore.tsx]"]
  node_login["Login<br/>[LoginPage.tsx]"]
  node_dashboard["Dashboard<br/>[DashboardPage.tsx]"]
  node_verification["Verification"]
  node_compliance["Compliance reports<br/>[CompliancePage.tsx]"]
  node_auditpage["Audit view<br/>[AuditPage.tsx]"]
  node_settings["Settings<br/>[SettingsPage.tsx]"]
end

subgraph group_audit["Independent audit"]
  node_offline["Offline record auditor<br/>[verify.js]"]
  node_record["Exported record"]
end

node_attendee(("Attendee"))
node_chain[("Blockchain network")]
node_validator(("Validator"))
node_facilitykey["Facility public key"]

node_attendee -->|"uses"| node_mobile
node_mobile -.->|"submits check-in"| node_checkin
node_server -->|"registers route"| node_checkin
node_server -->|"registers route"| node_tscbroute
node_server -->|"initializes"| node_database
node_server -->|"initializes"| node_crypto
node_server -->|"initializes"| node_geohash
node_database -->|"queries"| node_db
node_blockchain -->|"generates proof"| node_crypto
node_blockchain -->|"submits verification"| node_chain
node_validator -->|"uses"| node_portal
node_portal -->|"renders"| node_router
node_router -->|"checks session"| node_auth
node_router -->|"routes to"| node_login
node_router -->|"routes to"| node_dashboard
node_router -->|"routes to"| node_verification
node_router -->|"routes to"| node_compliance
node_router -->|"routes to"| node_auditpage
node_router -->|"routes to"| node_settings
node_record -->|"audits"| node_offline
node_facilitykey -->|"verifies signature"| node_offline

click node_mobile "https://github.com/cooldad7777/stamp-system/tree/main/mobile"
click node_checkin "https://github.com/cooldad7777/stamp-system/blob/main/backend/src/routes/checkin.ts"
click node_tscbroute "https://github.com/cooldad7777/stamp-system/blob/main/backend/src/routes/tscb-verify.ts"
click node_tscb "https://github.com/cooldad7777/stamp-system/blob/main/backend/src/crypto/TSCBProtocol.ts"
click node_crypto "https://github.com/cooldad7777/stamp-system/blob/main/backend/src/crypto/CryptoService.ts"
click node_geohash "https://github.com/cooldad7777/stamp-system/blob/main/backend/src/services/GeohashService.ts"
click node_server "https://github.com/cooldad7777/stamp-system/blob/main/backend/src/server.ts"
click node_database "https://github.com/cooldad7777/stamp-system/blob/main/backend/src/services/DatabaseService.ts"
click node_blockchain "https://github.com/cooldad7777/stamp-system/blob/main/backend/src/services/BlockchainVerificationService.ts"
click node_portal "https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/App.tsx"
click node_router "https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/components/AppRouter.tsx"
click node_auth "https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/stores/AuthStore.tsx"
click node_login "https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/pages/LoginPage.tsx"
click node_dashboard "https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/pages/DashboardPage.tsx"
click node_verification "https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/pages/VerificationPage.tsx"
click node_compliance "https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/pages/CompliancePage.tsx"
click node_auditpage "https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/pages/AuditPage.tsx"
click node_settings "https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/pages/SettingsPage.tsx"
click node_offline "https://github.com/cooldad7777/stamp-system/blob/main/stamp_verify/verify.js"

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_mobile,node_checkin,node_tscbroute toneBlue
class node_tscb,node_crypto,node_geohash,node_server,node_database,node_db,node_blockchain,node_chain toneAmber
class node_portal,node_router,node_auth,node_login,node_dashboard,node_verification,node_compliance,node_auditpage,node_settings toneMint
class node_offline,node_record toneRose
class node_attendee,node_validator,node_facilitykey toneIndigo
```

## Components

### Attendance proof

- [Mobile app](https://github.com/cooldad7777/stamp-system/tree/main/mobile): `mobile`
- [Check-in API](https://github.com/cooldad7777/stamp-system/blob/main/backend/src/routes/checkin.ts): `backend/src/routes/checkin.ts`
- [TSCB verify API](https://github.com/cooldad7777/stamp-system/blob/main/backend/src/routes/tscb-verify.ts): `backend/src/routes/tscb-verify.ts`

### Backend trust

- [TSCB protocol](https://github.com/cooldad7777/stamp-system/blob/main/backend/src/crypto/TSCBProtocol.ts): `backend/src/crypto/TSCBProtocol.ts`
- [Crypto service](https://github.com/cooldad7777/stamp-system/blob/main/backend/src/crypto/CryptoService.ts): `backend/src/crypto/CryptoService.ts`
- [Geohash service](https://github.com/cooldad7777/stamp-system/blob/main/backend/src/services/GeohashService.ts): `backend/src/services/GeohashService.ts`
- [API server](https://github.com/cooldad7777/stamp-system/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Database service](https://github.com/cooldad7777/stamp-system/blob/main/backend/src/services/DatabaseService.ts): `backend/src/services/DatabaseService.ts`
- **PostgreSQL**
- [Cross-jurisdiction verification](https://github.com/cooldad7777/stamp-system/blob/main/backend/src/services/BlockchainVerificationService.ts): `backend/src/services/BlockchainVerificationService.ts`

### Validator portal

- [Portal app](https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/App.tsx): `validator-portal/src/App.tsx`
- [Portal routing](https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/components/AppRouter.tsx): `validator-portal/src/components/AppRouter.tsx`
- [Auth state](https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/stores/AuthStore.tsx): `validator-portal/src/stores/AuthStore.tsx`
- [Login](https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/pages/LoginPage.tsx): `validator-portal/src/pages/LoginPage.tsx`
- [Dashboard](https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/pages/DashboardPage.tsx): `validator-portal/src/pages/DashboardPage.tsx`
- [Verification](https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/pages/VerificationPage.tsx): `validator-portal/src/pages/VerificationPage.tsx`
- [Compliance reports](https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/pages/CompliancePage.tsx): `validator-portal/src/pages/CompliancePage.tsx`
- [Audit view](https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/pages/AuditPage.tsx): `validator-portal/src/pages/AuditPage.tsx`
- [Settings](https://github.com/cooldad7777/stamp-system/blob/main/validator-portal/src/pages/SettingsPage.tsx): `validator-portal/src/pages/SettingsPage.tsx`

### Independent audit

- [Offline record auditor](https://github.com/cooldad7777/stamp-system/blob/main/stamp_verify/verify.js): `stamp_verify/verify.js`
- **Exported record**

### Other components

- **Attendee**
- **Blockchain network**
- **Validator**
- **Facility public key**

## Connections

- Attendee → Mobile app: uses
- Mobile app → Check-in API: submits check-in
- API server → Check-in API: registers route
- API server → TSCB verify API: registers route
- API server → Database service: initializes
- API server → Crypto service: initializes
- API server → Geohash service: initializes
- Database service → PostgreSQL: queries
- Cross-jurisdiction verification → Crypto service: generates proof
- Cross-jurisdiction verification → Blockchain network: submits verification
- Validator → Portal app: uses
- Portal app → Portal routing: renders
- Portal routing → Auth state: checks session
- Portal routing → Login: routes to
- Portal routing → Dashboard: routes to
- Portal routing → Verification: routes to
- Portal routing → Compliance reports: routes to
- Portal routing → Audit view: routes to
- Portal routing → Settings: routes to
- Exported record → Offline record auditor: audits
- Facility public key → Offline record auditor: verifies signature