AGENTS.md — ScrapYard (Hack the Globe 2026)

Construction surplus materials marketplace with AI-powered matching and carbon accounting. Hackathon project for Hack the Globe 2026 (Sustainable Infrastructure theme).

Project Structure

hack-the-globe/
  web/                # PRIMARY APP — Next.js 16 + Convex (TypeScript)
    src/
      components/     # Shared components (Layout, Logo, AuthContext, ui/)
      pages/          # Next.js Pages Router routes
      styles/         # Global CSS (Tailwind)
      lib/            # Utilities (cn helper)
    convex/           # Convex backend (schema, queries, mutations)
    public/           # Static assets (logos, icons)
    package.json
    components.json   # shadcn/ui config (radix-nova style)
  scrapyard/          # OLD MOCKUP — React + Vite prototype (JavaScript, do NOT develop here)
  pitch/              # Pitch plan, feedback notes
  docs/               # Hackathon guides, brainstorming, research
  .agents/skills/     # Convex agent skill definitions

All active development happens in web/. The scrapyard/ directory is an old mockup prototype.

Build / Lint / Dev Commands

Package manager: Bun

# All commands run from web/
cd web

# Install dependencies
bun install

# Development server (Next.js + Convex)
bun run dev

# Production build
bun run build

# Lint (ESLint 9 + next core-web-vitals + typescript)
bun run lint

There is no test framework configured.

Tech Stack

Convex Data Model

Three tables in convex/schema.ts:

listings

title, category, quantity, unit, price, originalPrice, seller, sellerRating, sellerVerified, sellerTransactions, carbonSaved, image (optional string), images (optional array of storage IDs), condition, description, location, lat, lng

Search index: by_category (searchField: title, filterFields: ["category"])

requests

title, category, budget, urgency, requester

messages

listingId (Id<"listings">), sender, body

Index: by_listingId on ["listingId"]

Convex Backend Functions

Routes (Pages Router)

shadcn/ui Components (Installed)

button, card, input, badge, dialog, label, chart, tabs

Config: radix-nova style, no RSC (rsc: false), neutral base color, CSS variables enabled.

Install more with: npx shadcn@latest add <component>

Shared Components

Code Style Guidelines

TypeScript

• All code is TypeScript (.tsx / .ts)
• Use proper types for Convex documents and IDs
• Zod for runtime validation (AI scanner responses)

Imports

• Path alias: @/* maps to ./src/*
• shadcn/ui imports: @/components/ui/button
• Convex imports: convex/_generated/api and convex/_generated/dataModel
• Single quotes for import strings

Component Patterns

• Default exports for page components
• Named exports for shared/ui components
• Props typed inline or with interfaces
• Pages Router conventions: useRouter() from next/router

Styling

• Tailwind CSS 4 for all styling — use utility classes
• CSS custom properties in globals.css for theme tokens (OKLCH color space)
• shadcn/ui components for consistent UI primitives
• No inline style={{}} objects — use Tailwind classes instead
• Animations: fade-up, fade-in, slide-up with stagger classes
• Mobile-first: max-width 430px app shell

State Management

• Convex useQuery for data fetching (reactive subscriptions)
• Convex useMutation for writes
• useAuth() custom hook for username (localStorage)
• Local useState for UI state
• useRouter() from next/router for navigation

Categories (Hardcoded)

lumber, steel, concrete, brick, glass, pipe, electrical, fixtures

These are currently defined as constants in multiple page files (not centralized).

Environment Variables

Key Reminders for Agents

1. Work in web/ — scrapyard/ is an old mockup, do not develop there
2. Use Bun, not npm/yarn
3. Use TypeScript — this is not a JavaScript project
4. Use Tailwind classes for styling, not inline style objects
5. Use shadcn/ui components (install with npx shadcn@latest add <name>)
6. Read convex/_generated/ai/guidelines.md before writing Convex code
7. Data is real (Convex), not mocked — use useQuery/useMutation
8. Pages Router (src/pages/), NOT App Router
9. Run bun run lint after changes
10. New pages go in src/pages/, new shared components in src/components/
11. AI scanner is real (Gemini via OpenRouter), not a mock
12. No SSR for Leaflet/map components — use next/dynamic with ssr: false