diff --git a/AGENTS.md b/AGENTS.md index c0770c8..8bb646e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,18 +1,25 @@ # Project tech stack + frontend: react, shadcn, tailwindcss -backend: convex +backend: go with go fiber as router # Project structure + This project uses npm workspaces. -- `packages/convex` - convex functions and models -- `apps/drive-web` - frontend dashboard -- `apps/file-proxy` - proxies uploaded files via opaque share tokens -- `packages/path` - path utils +- `apps/` - application code + - `drive-web` - web app for drexa drive, a cloud storage service + - `backend` - backend that powers drexa (will offer more services beyond drive in the future) + - `file-proxy` - deprecated go service to support the de +- `packages/` - reusable typescript code + - `convex` - deprecated convex backend that i am migrating away from + - `path` - deprecated path util for convex + - `auth` - deprecated auth package # General Guidelines +- IGNORE CONVEX. I DO NOT WANT CONVEX CODE ANYMORE. - For frontend dashboard guidelines, refer to dev/docs/dashboard.md -- Always use bun for package management and running npm scripts. +- For backend guidelines, refer to dev/docs/backend.md - When commiting, follow conventional commits: `[type]: msg` and clarify in commit body if necessary. keep your commit header to <= 50 characters. - `feat:` for new features - `fix:` for bug fixes @@ -22,7 +29,4 @@ This project uses npm workspaces. - `test:` for adding tests - `ci:` for CI/CD pipeline changes - `build:` for build system or dependency changes - -# Code styles - -- file names should always be kebab-case except in convex code, in which case try to use single word file names. +- ALWAYS use bun to run one-off JavaScript scripts. diff --git a/dev/docs/backend.md b/dev/docs/backend.md new file mode 100644 index 0000000..2b8f5c8 --- /dev/null +++ b/dev/docs/backend.md @@ -0,0 +1,47 @@ +# 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 + +- Account-scoped resources live under `/accounts/:accountID`; always apply auth + account 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 own accounts. +- Accounts own VFS nodes (files + directories). +- Auth grants own refresh tokens. +- Node share tokens exist for future sharing flows. + +# 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. diff --git a/dev/docs/dashboard.md b/dev/docs/dashboard.md index 828de09..f60e313 100644 --- a/dev/docs/dashboard.md +++ b/dev/docs/dashboard.md @@ -1,19 +1,30 @@ # Context -- tech stack: react, tailwindcss, shadcn, tanstack router, tanstack table, jotai +- tech stack: react, tailwindcss, shadcn, tanstack router, tanstack table, react-query, jotai - `@/` maps to `src/` -# Key files +# Key files/directories - `src/components`: reusable React components - `src/lib`: reusable util code - `src/routes`: tanstack file routes +- `src/vfs`: virtual file system related logic +- `src/user`: user logic and ui components +- `src/directories`: directory related logic and ui components # Guidelines - ALWAYS use absolute import using `@/`, unless the file is in the same directory. -- ALWAYS use kebab-case for file names -- when importing useQuery/useMutation from convex/react, alias them with useConvexQuery/useConvexMutation -- Do not attempt to create a preview server. There is one running already at port 3001. -- After create a new file route, run `bunx tsr generate` +- ALWAYS use kebab-case for file names. +- ALWAYS use bun to run scripts - No testing is in place right now, so skip that for now. +- Use biome for linting, formatting, and import ordering. +- Don't write test/docs unless asked. +- Put reusable code in their corresponding directories (eg `src/components`) +- Read `package.json` for available scripts. +- Always run lint and typecheck for files you modify before replying. +- Data fetching: use `src/lib/api.ts` (`fetchApi`) with arktype schemas; wrap queries/mutations with `queryOptions`/`mutationOptions` and prefer `atomWithQuery`/`atomFamily` for wiring. +- Auth/account context: account-scoped calls must only run when `currentAccountAtom` is set; use the `_authenticated` layout for gating and redirects. +- Routing: follow TanStack file-route conventions; `src/routeTree.gen.ts` is generated and should not be edited manually. +- UI: prefer shadcn components from `src/components/ui`, app-specific components in `src/components`, and shared helpers from `src/lib/utils` (`cn`). +- Error handling: use `defaultOnError` for user-facing failures and keep error mapping in `src/lib/error.ts`.