AGENTS.md

Project

МојМајстор — Expo React Native app connecting handymen with customers in Macedonia. Self-deployed Convex backend. All UI text in Macedonian; code variables and comments in English.

Tech Stack

Frontend: Expo SDK 56, React Native 0.85, TypeScript, Expo Router (file-based routing), inline styles (no NativeWind/Tailwind)
Backend: Convex (cloud at https://decisive-owl-34.eu-west-1.convex.cloud)
Auth: Custom email/password with SHA-256 (Convex actions), stored in accounts/sessions tables — no @convex-dev/auth (incompatible with self-hosted)
Deployment: EAS Build + Update

Convex Setup

Deploy with: npm run convex:dev or CONVEX_DEPLOYMENT="" npx convex dev --url https://backend-onhwnh06p0g3976vl34yx18v.testbed.mk:3210 --once
Self-deployed Convex does not support searchIndex — use .filter() for search instead
Self-deployed Convex does not support @convex-dev/auth — custom auth via convex/auth.ts
Auth env vars already set: AUTH_SECRET, AUTH_SECRET_1-AUTH_SECRET_10, AUTH_URL

Design System

Colors: Warm terracotta (#D4764A) + deep navy (#1A2A3A), off-white bg (#FDF8F3)
Typography: System font, hierarchy via theme.typography (h1/h2/h3/body/caption/label)
Shadows: Defined in theme.shadows as { shadowColor, shadowOffset, shadowOpacity, shadowRadius, elevation }
Theme context via ThemeProvider + useTheme() from components/theme.tsx
Spacing: 4/8/16/24/32/48 via theme.spacing, radius via theme.radius
Icons: @expo/vector-icons (Ionicons) for tab bar; emoji for categories
Styling: Inline styles only, no NativeWind, no StyleSheet.create
Card variants: default (border), elevated (shadow), outlined (transparent bg + border)
Button variants: primary (terracotta + shadow), secondary (surface + border), outline, ghost, destructive
Language split: Macedonian for all user-facing text, English for code
Role system: handyman | customer — set at registration. Handymen create ads; customers create posts; both can chat
Auth token: Stored in localStorage, passed to Convex queries/mutations as token argument. Verified server-side via sessions table
Styling: Inline styles only, using useTheme() hook from components/theme.tsx. No NativeWind, no StyleSheet.create
Convex paths: convex/ — one file per domain. Schema in convex/schema.ts. Never edit convex/_generated/

Route Structure

app/
  _layout.tsx          — Root: ConvexProvider + ThemeProvider + AuthContext + ErrorBoundary
  (auth)/
    login.tsx           — Email/password login
    register.tsx        — Role selection (handyman/customer) + profile creation
  (tabs)/
    (home)/index.tsx    — Home: search + categories + recent ads
    (explore)/index.tsx — Browse categories & filtered ads
    (posts)/index.tsx   — Customer needs feed (open/all tabs)
    (chat)/index.tsx    — Chat list
    (profile)/index.tsx — User profile, my ads/posts
  ad/
    [id].tsx            — Ad detail with reviews & chat button
    create.tsx          — 4-step ad creation form
  post/
    [id].tsx            — Post detail with respond button
    create.tsx          — Create customer need
  chat/
    [id].tsx            — Chat conversation
  review/
    create.tsx          — Star rating + review form

Commands

npx expo start                                           # Dev server
npx expo start --dev-client                              # Dev server with dev client
npm run convex:dev                                       # Convex backend dev
npx convex deploy                                        # Deploy to cloud
npx tsc --noEmit                                         # Type check

Constraints

Max 5 images per ad (stored as string IDs in schema, not _storage refs)
All timestamps are Date.now() milliseconds
Roles stored as v.string() (not v.union(v.literal(...))) due to self-deployed Convex compatibility
useAuth() export from app/_layout.tsx provides { token, userId, isAuthenticated, login, logout }
Deep links: mojmajstor://ad/[id], mojmajstor://chat/[id]

Full Plan

See implementation.md for phased implementation details and data model.

This project uses Convex as its backend.

When working on Convex code, always read convex/_generated/ai/guidelines.md first for important guidelines on how to correctly use Convex APIs and patterns. The file contains rules that override what you may have learned about Convex from training data.

Convex agent skills for common tasks can be installed by running npx convex ai-files install.

4.7 KiB Raw Permalink Blame History