Imported from kyaw-hlaing-soe-dev/CampusLoop (AGENTS.md). Install upstream with npx skills add kyaw-hlaing-soe-dev/CampusLoop. Copyright stays with the author.

CampusLoop Repository Guide

Product Scope

CampusLoop is a frontend-only, mobile-first marketplace web app for university students. It is not a native application and must not gain backend, payment, realtime, or server infrastructure without an explicit scope change. Product behavior uses typed mock services, React state, browser APIs, and localStorage.

Clean Architecture and Structure

• src/components/: reusable presentation components grouped by feature.
• src/data/: deterministic mock marketplace data.
• src/services/: mock repositories and service boundaries for future API replacement.
• src/store/: application state, persistence, actions, and orchestration.
• src/types/: strict domain contracts.
• src/styles/: global theme, layout, motion, and responsive styles.
• src/test/: test setup and behavior tests.
• public/assets/: optimized static product and brand assets.
• docs/: durable product and implementation specifications.

Dependencies flow toward the domain: presentation consumes store actions and service interfaces; domain rules do not import React or browser UI. Keep modules cohesive, functions small, names intention-revealing, and state changes explicit. Avoid duplicate logic, boolean-heavy APIs, any, catch-all utilities, and monolithic screen files.

Commands

• npm run dev: start Vite locally.
• npm run typecheck: validate strict TypeScript.
• npm run lint: run ESLint.
• npm test: run the Vitest suite once.
• npm run build: type-check and create the production bundle.

Implementation Rules

• Design for 320–480px viewports first. Desktop only centers the mobile shell; never add a desktop dashboard, sidebar, or wide grid.
• Use semantic HTML, 44px minimum interactive targets, visible focus styles, and descriptive accessible names.
• Use 100dvh, safe-area environment variables, and at least 16px form fields.
• Keep content surfaces crisp. Reserve translucent glass for floating navigation, sheets, search, icon buttons, and segmented controls.
• Enforce listing rules in the domain/service layer: free means zero price, used requires condition, new gets NEW, removed listings do not appear publicly, and unavailable or owned listings cannot be reserved.
• Keep mock service signatures compatible with a future HTTP implementation, but do not add network calls.
• Revoke object URLs created for local image previews when removed or no longer needed. Never persist blob: URLs.

Use two-space indentation. Components and types use PascalCase; variables and functions use camelCase; general filenames use kebab-case except React component files. Preserve the muted sage/slate identity and intentional dark theme. Avoid unrelated refactors.

Testing and Verification

Add deterministic tests for domain rules and important interaction changes. Before final handoff run typecheck, lint, tests, and the production build. Inspect rendered behavior at 320, 360, 375, 390, 412, and 430px, including safe areas, fixed navigation, sheets, dark mode, overflow, and keyboard-friendly forms.

Commits

Use short, imperative Conventional Commit subjects. Keep commits focused and independently understandable. Never commit secrets, dependency directories, production credentials, or unrelated work.