mojmajstor/implementation.md

МојМајстор - Implementation Plan

Overview

МојМајстор (My Handyman) is a mobile app connecting local handymen with customers in Macedonia. Built with Expo React Native and a self-deployed Convex backend, all UI text in Macedonian.

---

Tech Stack

Layer	Technology
Frontend	Expo SDK 52+, React Native, TypeScript
Navigation	Expo Router (file-based)
Backend	Convex (self-hosted)
Auth	Convex Auth (email/password + phone)
Styling	NativeWind (Tailwind for RN)
Chat	Convex real-time queries
Maps	react-native-maps
Image Upload	Convex file storage + expo-image-picker
Deployment	EAS Build + Update

---

Data Model (Convex Schema)

users

• _id, name, phone, email, role ("handyman" | "customer"), avatarId?, createdAt

ads

• _id, handymanId (ref users), title, description, category, location, lat?, lng?, priceRange?, imageIds[], availability, ratingAvg?, reviewCount, createdAt, updatedAt

categories

• _id, name (Macedonian), slug, icon?, sortOrder

reviews

• _id, adId (ref ads), customerId (ref users), handymanId (ref users), rating (1-5), comment, createdAt

chats

• _id, participantIds[] (ref users), lastMessageAt, createdBy

messages

• _id, chatId (ref chats), senderId (ref users), content, imageId?, createdAt

posts (customer needs)

• _id, customerId (ref users), title, description, category, location, budget?, status ("open" | "closed"), createdAt, updatedAt

---

Project Structure

mojmajstor/
├── app/                          # Expo Router pages
│   ├── _layout.tsx               # Root layout + auth state
│   ├── (auth)/
│   │   ├── _layout.tsx
│   │   ├── login.tsx
│   │   └── register.tsx
│   ├── (tabs)/
│   │   ├── _layout.tsx           # Bottom tab navigator
│   │   ├── index.tsx             # Home / search
│   │   ├── explore.tsx           # Browse categories & ads
│   │   ├── posts.tsx             # Customer needs feed
│   │   ├── chat.tsx             # Chat list
│   │   └── profile.tsx          # User profile
│   ├── ad/
│   │   ├── [id].tsx              # Ad detail
│   │   └── create.tsx            # Create ad (handyman)
│   ├── post/
│   │   ├── [id].tsx              # Post detail
│   │   └── create.tsx            # Create post (customer)
│   ├── chat/
│   │   └── [id].tsx              # Chat conversation
│   └── review/
│       └── create.tsx            # Leave a review
├── components/
│   ├── ui/                       # Reusable UI primitives
│   │   ├── Button.tsx
│   │   ├── Card.tsx
│   │   ├── Input.tsx
│   │   ├── Rating.tsx
│   │   ├── Avatar.tsx
│   │   ├── Badge.tsx
│   │   └── Loading.tsx
│   ├── AdCard.tsx
│   ├── PostCard.tsx
│   ├── ChatListItem.tsx
│   ├── MessageBubble.tsx
│   ├── CategoryGrid.tsx
│   ├── SearchBar.tsx
│   ├── LocationPicker.tsx
│   └── ReviewCard.tsx
├── convex/                       # Backend
│   ├── _generated/
│   ├── schema.ts
│   ├── auth.config.ts
│   ├── users.ts
│   ├── ads.ts
│   ├── categories.ts
│   ├── reviews.ts
│   ├── chats.ts
│   ├── messages.ts
│   └── posts.ts
├── lib/
│   ├── constants.ts              # Colors, spacing, Macedonian strings
│   ├── hooks.ts                  # Custom hooks
│   └── utils.ts
├── assets/
│   └── images/
├── app.json
├── package.json
├── tailwind.config.js
├── tsconfig.json
└── eas.json

---

Implementation Phases

Phase 1: Project Setup & Auth (Week 1)

Goal: Bootable app with authentication.

1. Initialize Expo project with TypeScript template
2. Install dependencies: expo-router, nativewind, convex, @convex-dev/auth, expo-image-picker, react-native-maps, expo-location
3. Configure NativeWind (Tailwind) + constants (colors, Macedonian strings)
4. Set up Convex project & self-deploy
5. Define schema.ts with all tables
6. Configure Convex Auth (email/password + phone)
7. Build root _layout.tsx with auth state observer
8. Build (auth)/login.tsx - email/phone login
9. Build (auth)/register.tsx - role selection (handyman/customer) + profile creation
10. Build UI primitives: Button, Input, Card, Loading

Deliverable: User can sign up, log in, see role-specific tab layout.

---

Phase 2: Home & Categories (Week 2)

Goal: Browse and discover handymen.

1. Seed categories table (Мајстор за сѐ, Водоинсталатер, Електричар, Тескар, Фарбар, Керамичар, Зидар, Градежник, столар, Молер, Електричар, Клима монтажер, etc.)
2. Build (tabs)/_layout.tsx - bottom nav (Почетна, Пребарување, Огласи, Чат, Профил)
3. Build (tabs)/index.tsx - home screen with hero search + category grid + featured ads
4. Build CategoryGrid component with icons per category
5. Build SearchBar component with text + location filter
6. Build (tabs)/explore.tsx - category list → filtered ad list
7. Build AdCard component (image, title, rating, location, price range)
8. Create ads.ts Convex queries: list, getByCategory, search, getByHandyman
9. Wire up real data to ad listings

Deliverable: Customer can browse categories and see handyman ads.

---

Phase 3: Ad Creation & Detail (Week 3)

Goal: Handymen can post and manage ads.

1. Build ad/create.tsx - multi-step form:
   • Step 1: Category selection
   • Step 2: Title, description, price range
   • Step 3: Location (map picker or text)
   • Step 4: Availability schedule
   • Step 5: Photo upload (up to 5)
2. Build ad/[id].tsx - ad detail page:
   • Gallery, description, location map, availability, rating, reviews
   • "Започни разговор" (Start chat) button
   • "Напиши оценка" (Write review) button
3. Create ads.ts mutations: create, update, delete
4. Handle image upload via Convex file storage + expo-image-picker
5. Build profile.tsx - handyman view with their ads list, edit/delete

Deliverable: Handymen can create, view, edit, delete their ads. Customers can view full details.

---

Phase 4: Customer Posts (Week 4)

Goal: Customers can post their needs; handymen can respond.

1. Build post/create.tsx - customer need form (title, description, category, location, budget, urgency)
2. Build post/[id].tsx - post detail with responses
3. Build (tabs)/posts.tsx - feed of open customer posts
4. Create posts.ts Convex queries & mutations: create, list, getByCustomer, close
5. Add "Одговори на оглас" (Respond to post) flow for handymen → starts a chat

Deliverable: Customers post needs, handymen browse and respond.

---

Phase 5: In-App Chat (Week 5)

Goal: Real-time messaging between customer and handyman.

1. Build (tabs)/chat.tsx - chat list with last message preview, unread indicator
2. Build chat/[id].tsx - full conversation screen with:
   • Message bubbles (text + optional image)
   • Input bar with send button + image picker
   • Real-time updates via Convex onUpdate
3. Create chats.ts Convex queries & mutations: create, listByUser
4. Create messages.ts Convex queries & mutations: send, listByChat (paginated)
5. Add push notification support via Expo Notifications
6. Add "Започни разговор" button on ad detail → creates or opens existing chat

Deliverable: Users can chat in real-time with image support.

---

Phase 6: Reviews & Ratings (Week 6)

Goal: Customer can rate and review handymen.

1. Build review/create.tsx - star rating + comment form
2. Build ReviewCard component
3. Add review summary to AdCard and ad detail page
4. Create reviews.ts Convex queries & mutations: create, getByAd, getByHandyman
5. Update ads table: compute ratingAvg and reviewCount on review creation (Convex trigger)
6. Sort ads by rating in search/explore

Deliverable: Customers leave reviews; ratings visible on ads.

---

Phase 7: Polish & Production (Week 7)

Goal: Production-ready app.

1. Full Macedonian localization (all strings in lib/constants.ts)
2. Error handling & loading states on every screen
3. Pull-to-refresh on list screens
4. Pagination on ad feeds and chat messages
5. Offline-first considerations (Convex optimistic updates)
6. Deep linking configuration
7. App icon & splash screen (Macedonian-themed)
8. EAS Build configuration for iOS + Android
9. App store metadata (Македонски)
10. Performance audit (list virtualization, image optimization)
11. Accessibility pass (labels, contrast, font scaling)

Deliverable: Published app on App Store & Google Play.

---

Key Decisions & Notes

• Language: All user-facing text is in Macedonian (Македонски). Code variables and comments in English.
• Role system: Determined at registration. Handymen see ad creation; customers see post creation. Both can chat.
• Maps: Use react-native-maps with OpenStreetMap tiles (no Google API key needed for MVP).
• Convex self-deploy: Deploy via Docker on own infra for full data sovereignty.
• Auth strategy: Start with email/password, add phone OTP via Twilio in Phase 7.
• Image optimization: Compress before upload using expo-image-manipulator. Max 5 images per ad.
• Search: Convex full-text search on ad title/description. Location filter via lat/lng bounding box.