App Architecture
Private upload and account boundary
Recommended first secure application slice for Circuit Genome: authenticated users, account-scoped uploads, private storage, and per-request authorization on every file read, analysis, download, and delete action.
Status
| Audience | App implementers planning the first authenticated upload workflow. |
| First Milestone | A logged-in user can upload a file and only that user can see it. |
| Current Repo Reality | Static marketing/docs site plus a small serverless contact endpoint. |
| Storage Rule | User uploads must not live in a public web folder or in the public site repo. |
Non-Negotiable Rules
- Every upload record must include a
user_id owner reference.
- File contents must live in private storage, not under a public URL.
- The backend must verify session and file ownership on every read, download, analyze, rename, and delete request.
- Frontend state is advisory only; privacy enforcement lives on authenticated backend routes.
- Metadata and file content should be separated: relational database for records, private object storage for bytes.
Recommended System Boundary
| Area |
What Lives There |
What Does Not |
| Public site | Marketing pages, docs, exporter downloads, examples. | User uploads, session data, private reports. |
| Private app | Accounts, sessions, uploads, analyzer jobs, per-user reports. | Anonymous public file access. |
| Database | Users, sessions, upload metadata, processing state, audit events. | Large raw file payloads. |
| Private object storage | Uploaded source files and derived private artifacts. | Public web assets and docs. |
First-Version Pages
| Page |
Purpose |
Access |
/signup | Create an account. | Public |
/login | Authenticate and create a session. | Public |
/dashboard | List only the current user's uploads. | Authenticated |
/uploads/new | Upload a new source file. | Authenticated |
/uploads/:id | Show metadata, validation, and future analysis outputs for one owned file. | Authenticated + owner-only |
Core API Surface
| Route |
Purpose |
Security Requirement |
POST /api/auth/signup | Create user + password hash. | Rate limit and validate email/password policy. |
POST /api/auth/login | Create authenticated session cookie. | HTTP-only, secure, same-site cookie. |
POST /api/auth/logout | Invalidate the current session. | Must clear session server-side and client-side. |
GET /api/uploads | Return uploads owned by the current user. | Never return cross-account rows. |
POST /api/uploads | Store file metadata and private file bytes. | Authenticated only; validate size, type, and filename. |
GET /api/uploads/:id | Return one upload's metadata. | Deny by default unless upload.user_id === session.user_id. |
GET /api/uploads/:id/download | Stream the owned file from private storage. | Owner check on every request. |
DELETE /api/uploads/:id | Delete one owned upload. | Owner check plus audit event. |
Minimal Data Model
| Table |
Key Fields |
Notes |
users | id, email, password_hash, created_at | Email should be unique and normalized. |
sessions | id, user_id, expires_at, created_at | Store only opaque session IDs server-side. |
uploads | id, user_id, original_filename, storage_key, mime_type, size_bytes, uploaded_at, processing_status | This is the ownership boundary for private files. |
upload_events | id, upload_id, event_type, created_at, metadata_json | Useful for audit trail and troubleshooting. |
Implementation Notes
- Use a modern password hashing function and store only password hashes, never plaintext passwords.
- Use opaque server-side session IDs in cookies rather than putting authorization logic in the client.
- Set private app responses to restrictive cache behavior because they can contain sensitive metadata or file URLs.
- Log upload create, read, download, delete, and analysis actions so account activity is reviewable later.
- Start with single-user ownership. Add organizations and shared projects only after the owner-only path is proven correct.
Suggested Build Sequence
| Phase |
Deliverable |
Outcome |
| 1 | Signup, login, logout, protected dashboard. | Users can authenticate and see only their own workspace shell. |
| 2 | Private upload endpoint + owned file list + file detail page. | The account boundary exists for stored source files. |
| 3 | Validation and analysis job status. | Uploads become usable artifacts rather than stored files only. |
| 4 | Delete, rename, derived artifacts, and audit trail. | The private workflow becomes operationally manageable. |
| 5 | Organizations, shared projects, quotas, and billing. | Collaboration and commercial controls can be added on top of a correct ownership model. |
Practical stack note: if this site stays on a Vercel-style serverless deployment, keep file bytes in private object storage and keep metadata in a relational database. Do not treat the function filesystem or the site repo as durable private user storage.