Imported from Notso-sahil/CampUs (AGENTS.md). Install upstream with npx skills add Notso-sahil/CampUs. Copyright stays with the author.

CampUs — Agent Engineering Standards

CampUs is a multi-tenant college-lifestyle platform for Indian students covering: a buy/sell marketplace (Trade), lost & found (Recover), knowledge document hub, peer services marketplace, team finder, roommate finder, and a real-time messaging layer. Auth is handled by an auth provider (Firebase), the DB is a relational database (Neon Postgres), and files are stored in object storage (Cloudflare R2) with SHA-256 content-addressing for deduplication.

Repositories

Exact Commands (verified from package.json)

Frontend (CampUs/)

npm run dev          # Dev server on port 8080
npm run build        # Production build → dist/
npm run lint         # ESLint flat config (TS + react-hooks + react-refresh)
npm run test         # Vitest one-shot (jsdom environment)
npm run test:watch   # Vitest watch
npx tsc --noEmit     # Type-check only

Backend (CampUs-api/)

npm run dev   # node --watch server.js
npm start     # node server.js (production)

No lint, test, or type-check scripts exist on the backend today.

Scan Worker (campus-scan-worker/)

npx wrangler dev     # local dev
npx wrangler deploy  # deploy to Cloudflare

Directory Map

Frontend CampUs/src/

components/         Reusable UI (Navbar, cards, modals)
  └── ui/           UI library primitives — never hand-edit, use CLI
contexts/           AuthContext, CollegeContext (React context providers)
hooks/              Custom hooks (use-toast, use-mobile)
lib/                Utilities: api.ts, firebase.ts, uploadToStorage.ts, workers
pages/              Route-level page components (PascalCase.tsx)
  └── admin/        Admin panel sub-pages
test/               Vitest setup + spec files
types/              Shared TypeScript type definitions

Backend CampUs-api/

api/                One handler file per endpoint (kebab-case.js)
controllers/        Complex business logic (admin.controller.js)
middleware/         auth.js (token verification), rbac.js (admin role check)
lib/                Auth admin singleton (firebase-admin.js)
routes/             admin.routes.js (Express Router for /api/admin/*)
*.js (root)         Migration scripts — ALREADY APPLIED, do not re-run

Naming Conventions (observed)

Files the Agent Must Never Auto-Modify

Critical Architectural Rules (Quick Ref)

1. Database queries: Tagged template literals ONLY — sql`...${param}`. Never sql(string, args).
2. File deletion: Decrement file_hashes.reference_count; only call object storage DeleteObjectCommand when it reaches 0.
3. Auth: Every mutating route requires token verification middleware → req.uid; admin routes additionally call requireAdmin.
4. Upload pipeline: compress → hash (Web Worker) → dedup check (get-upload-url) → presigned PUT to object storage → finalize-upload.
5. Size limits: 25 MB max for knowledge docs; 5 MB for images in all other contexts.
6. Homepage resilience: Use Promise.allSettled, never Promise.all, for multi-endpoint fetches on shared pages.
7. Data fetching: All new data-fetching must use useQuery/useMutation from the server state library (TanStack Query). Raw useState + useEffect fetch patterns are deprecated for new code.

Rules Index

Reusing These Rules in a New Project

The /rules/ folder is a portable starter kit. To apply it to a new codebase:

1. Copy the entire /rules/ folder into the new repo root.
2. Create a fresh /AGENTS.md for the new project (do not copy this file).
3. Inspect the new codebase (stack, commands, conventions, secrets pattern).
4. In each /rules/*.md file, keep all PRINCIPLE: lines untouched — they are stack-agnostic and always valid.
5. Regenerate only the HERE: lines based on the new codebase's actual libraries and patterns. The general-term format (database (ToolName), auth provider (ToolName), bundler (ToolName)) makes it clear which parts are stack-specific.
6. If a principle is genuinely inapplicable to the new project's domain, note why it is skipped rather than silently deleting it.