mirror of
https://github.com/get-drexa/drive.git
synced 2026-02-02 11:41:18 +00:00
48 lines
2.0 KiB
Markdown
48 lines
2.0 KiB
Markdown
# Backend guidelines
|
|
|
|
- Stack: Go + Fiber + Bun ORM + Postgres, with JWT-based auth.
|
|
- Keep handlers thin; put domain logic in services and persistence in database/virtualfs/blob layers.
|
|
- Keep packages focused: auth, user, account, catalog (HTTP for VFS), upload, virtualfs, blob, database.
|
|
- Use public IDs in API responses and inputs; internal UUIDs stay server-side.
|
|
|
|
# Routing + auth conventions
|
|
|
|
- Drive-scoped resources live under `/drives/:driveID`; always apply auth + drive middleware.
|
|
- Auth middleware must be the source of truth for the current user (via `reqctx`).
|
|
- Support both bearer-token and cookie flows; pick one per client surface.
|
|
- Use transactions for multi-step writes or cross-table changes.
|
|
|
|
# Data model relationships (high level)
|
|
|
|
- Users have accounts (principals) within organizations.
|
|
- Drives own VFS nodes (files + directories).
|
|
- Auth grants own refresh tokens.
|
|
- Node shares grant scoped access into drives.
|
|
|
|
# Virtual filesystem + storage
|
|
|
|
- Files and directories are both VFS nodes; use the VirtualFS API for create/move/rename/delete.
|
|
- Soft delete supports “trash” behavior; permanent delete removes data + blobs.
|
|
- Storage mode/backends influence blob keys; do not assume a single strategy.
|
|
- Any operation that changes paths must keep the blob store in sync.
|
|
|
|
# Uploads
|
|
|
|
- Uploads are staged then finalized; treat pending uploads as ephemeral.
|
|
- Finalization is responsible for setting metadata and moving the node to a usable state.
|
|
|
|
# Error handling
|
|
|
|
- Wrap failures with `httperr` helpers; return JSON `{ "error": "..." }`.
|
|
- Prefer explicit status codes for user-visible failures; log internal errors.
|
|
|
|
# Docs + tooling
|
|
|
|
- Keep swag annotations current when endpoints or response shapes change.
|
|
- Update the OpenAPI patching logic when you introduce new union-like types.
|
|
|
|
# Configuration
|
|
|
|
- Config is YAML-driven; see `apps/backend/config.example.yaml` for required fields and env overrides.
|
|
- Keep CORS and cookie settings aligned with the frontend deployment topology; cookie `Secure` is derived from request protocol.
|