Skip to content

agent.md

Latest commit

 

History

History
98 lines (80 loc) · 3.15 KB

agent.md

File metadata and controls

98 lines (80 loc) · 3.15 KB
Raw
name cubby-server-agent
version 1
purpose Project-specific operating guide for AI coding agents working in this repository.

Cubby Server Agent Guide

Project Snapshot

Cubby Server is a Fastify + TypeScript backend for self-hosted file storage. It provides JWT auth, file/folder APIs, and S3-compatible object storage integration backed by PostgreSQL via Prisma.

Tech Stack

  • Runtime: Node.js + TypeScript (ESM)
  • HTTP framework: Fastify
  • Auth: @fastify/jwt + bcrypt
  • Database: PostgreSQL + Prisma
  • Object storage: S3-compatible providers via AWS SDK v3
  • API docs: OpenAPI via @fastify/swagger and @fastify/swagger-ui

Source Map

  • Entry point: src/index.ts
  • Routes:
    • src/routes/auth.ts
    • src/routes/users.ts
    • src/routes/files.ts
    • src/routes/folders.ts
  • Services:
    • src/services/auth.service.ts
    • src/services/storage.service.ts
  • DB client: src/lib/prisma.ts
  • Shared utilities:
    • src/utils/pagination.ts
    • src/config/mime-types.ts
  • Prisma schema split:
    • prisma/schema/_schema.prisma
    • prisma/schema/user.prisma
    • prisma/schema/file.prisma
    • prisma/schema/folder.prisma

Existing API Capabilities

  • Auth
    • Register, login, and current-user profile (/api/auth/register, /api/auth/login, /api/auth/me)
  • Users
    • CRUD endpoints in /api/users (legacy create route is marked deprecated)
  • Files
    • Authenticated upload, list (paginated), download, and delete in /api/files
    • Upload currently accepts image MIME types only
    • Per-user quota checks and used-space tracking
  • Folders
    • Create/list/get contents/rename/delete in /api/folders
    • Folder paths are unique per user; rename updates descendants
  • Platform
    • Health endpoint (/health)
    • Swagger UI at /docs

Commands

  • Dev server: npm run dev
  • Build: npm run build
  • Start compiled app: npm run start
  • Interactive setup (PowerShell): npm run setup:ps
  • Interactive setup (Bash): npm run setup:sh
  • Prisma generate: npm run prisma:generate
  • Prisma migrate: npm run prisma:migrate
  • DB helpers:
    • npm run db:up
    • npm run db:down
    • npm run db:logs
    • npm run db:reset

Working Rules For Agents

  • Preserve TypeScript + ESM style already used in src/.
  • Keep Fastify schemas aligned with actual response payloads.
  • Prefer service-layer changes for reusable business logic over route-level duplication.
  • Respect existing soft-delete behavior (isDeleted, deletedAt) for files and folders.
  • For storage changes, keep DB and S3 operations consistent (avoid orphaned records/objects).
  • Keep pagination behavior consistent with src/utils/pagination.ts.
  • If adding upload types, update both src/config/mime-types.ts and route descriptions.

Environment Expectations

This app expects environment variables for:

  • Server: PORT, HOST, JWT_SECRET
  • Database: DATABASE_URL
  • S3: S3_ENDPOINT, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY, S3_BUCKET, S3_FORCE_PATH_STYLE

Current Constraints

  • Project is actively evolving and not production-hardened yet.
  • No test suite is currently present in this repository.
  • Some endpoints expose user management broadly; apply stricter authorization before production use.