CLAUDE.md

1# CLAUDE.md — Glomon Homes Real Estate Website
2 
3## Project Overview
4 
5**Company:** Glomon Homes  
6**Tagline:** *Find Your Place in Uganda*  
7**Type:** Full-stack real estate listings and property development website  
8**Market:** Uganda — primary focus on Kampala and surrounding areas (Wakiso, Mukono, Entebbe corridor)  
9**Target Audience:**
10- Local Ugandan buyers and renters
11- Ugandan diaspora investing from abroad
12- Expats relocating to Uganda
13- Property investors seeking development opportunities
14 
15---
16 
17## Tech Stack
18 
19### Frontend
20- **Framework:** React 18 + Vite
21- **Styling:** Tailwind CSS v3
22- **Routing:** React Router v6
23- **State Management:** React Context API (no Redux — keep it lean)
24- **HTTP Client:** Axios
25- **Icons:** Lucide React
26- **Image Handling:** Cloudinary (free tier) for property images
27- **Environment Variables:** `.env` using `VITE_` prefix
28 
29### Backend
30- **Runtime:** Node.js (v18+)
31- **Framework:** Express.js
32- **ORM:** Prisma
33- **Database:** PostgreSQL (hosted on Supabase)
34- **Auth:** JSON Web Tokens (JWT) for admin authentication
35- **File Uploads:** Multer + Cloudinary SDK
36- **Validation:** Zod
37- **Environment Variables:** dotenv
38 
39### Database
40- **Provider:** Supabase (PostgreSQL)
41- **ORM:** Prisma with migrations
42 
43### Deployment
44- **Frontend:** Vercel
45- **Backend:** Railway
46- **Database:** Supabase (free tier)
47- **Images:** Cloudinary (free tier)
48 
49---
50 
51## Folder Structure
52 
53```
54glomon-homes/
55├── CLAUDE.md
56├── .gitignore
57├── README.md
58│
59├── frontend/
60│   ├── public/
61│   │   └── favicon.ico
62│   ├── src/
63│   │   ├── assets/
64│   │   │   └── logo.svg
65│   │   ├── components/
66│   │   │   ├── layout/
67│   │   │   │   ├── Navbar.jsx
68│   │   │   │   └── Footer.jsx
69│   │   │   ├── properties/
70│   │   │   │   ├── PropertyCard.jsx
71│   │   │   │   ├── PropertyGrid.jsx
72│   │   │   │   ├── PropertyFilters.jsx
73│   │   │   │   └── PropertyImageGallery.jsx
74│   │   │   ├── ui/
75│   │   │   │   ├── Button.jsx
76│   │   │   │   ├── Badge.jsx
77│   │   │   │   ├── Spinner.jsx
78│   │   │   │   └── Modal.jsx
79│   │   │   └── forms/
80│   │   │       ├── EnquiryForm.jsx
81│   │   │       └── ContactForm.jsx
82│   │   ├── pages/
83│   │   │   ├── HomePage.jsx
84│   │   │   ├── ListingsPage.jsx
85│   │   │   ├── PropertyDetailPage.jsx
86│   │   │   ├── AboutPage.jsx
87│   │   │   ├── ContactPage.jsx
88│   │   │   └── NotFoundPage.jsx
89│   │   ├── admin/
90│   │   │   ├── AdminLoginPage.jsx
91│   │   │   ├── AdminDashboard.jsx
92│   │   │   ├── AdminProperties.jsx
93│   │   │   ├── AdminAddProperty.jsx
94│   │   │   ├── AdminEditProperty.jsx
95│   │   │   └── AdminEnquiries.jsx
96│   │   ├── context/
97│   │   │   └── AuthContext.jsx
98│   │   ├── hooks/
99│   │   │   ├── useProperties.js
100│   │   │   └── useEnquiries.js
101│   │   ├── services/
102│   │   │   └── api.js
103│   │   ├── utils/
104│   │   │   └── formatters.js
105│   │   ├── App.jsx
106│   │   └── main.jsx
107│   ├── index.html
108│   ├── vite.config.js
109│   ├── tailwind.config.js
110│   └── package.json
111│
112└── backend/
113    ├── prisma/
114    │   ├── schema.prisma
115    │   └── seed.js
116    ├── src/
117    │   ├── routes/
118    │   │   ├── properties.js
119    │   │   ├── enquiries.js
120    │   │   └── auth.js
121    │   ├── controllers/
122    │   │   ├── propertiesController.js
123    │   │   ├── enquiriesController.js
124    │   │   └── authController.js
125    │   ├── middleware/
126    │   │   ├── authMiddleware.js
127    │   │   ├── validateRequest.js
128    │   │   └── errorHandler.js
129    │   ├── lib/
130    │   │   └── prisma.js
131    │   └── index.js
132    ├── .env
133    └── package.json
134```
135 
136---
137 
138## Database Schema (Prisma)
139 
140```prisma
141// prisma/schema.prisma
142 
143generator client {
144  provider = "prisma-client-js"
145}
146 
147datasource db {
148  provider = "postgresql"
149  url      = env("DATABASE_URL")
150}
151 
152model Property {
153  id            String      @id @default(cuid())
154  title         String
155  description   String
156  price         Float
157  priceType     PriceType   @default(SALE)
158  currency      String      @default("UGX")
159  propertyType  PropertyType
160  status        ListingStatus @default(ACTIVE)
161  bedrooms      Int?
162  bathrooms     Int?
163  area          Float?       // square meters
164  location      String       // e.g. "Kololo, Kampala"
165  district      String       // e.g. "Kampala"
166  address       String?
167  latitude      Float?
168  longitude     Float?
169  images        String[]     // Cloudinary URLs
170  coverImage    String?      // Main display image URL
171  featured      Boolean      @default(false)
172  amenities     String[]     // e.g. ["Parking", "Security", "Swimming Pool"]
173  enquiries     Enquiry[]
174  createdAt     DateTime     @default(now())
175  updatedAt     DateTime     @updatedAt
176}
177 
178model Enquiry {
179  id          String    @id @default(cuid())
180  name        String
181  email       String
182  phone       String?
183  message     String
184  propertyId  String?
185  property    Property? @relation(fields: [propertyId], references: [id])
186  status      EnquiryStatus @default(NEW)
187  createdAt   DateTime  @default(now())
188}
189 
190model AdminUser {
191  id        String   @id @default(cuid())
192  email     String   @unique
193  password  String   // bcrypt hashed
194  createdAt DateTime @default(now())
195}
196 
197enum PropertyType {
198  APARTMENT
199  HOUSE
200  VILLA
201  COMMERCIAL
202  LAND
203  OFFICE
204}
205 
206enum PriceType {
207  SALE
208  RENT
209}
210 
211enum ListingStatus {
212  ACTIVE
213  INACTIVE
214  SOLD
215  RENTED
216}
217 
218enum EnquiryStatus {
219  NEW
220  READ
221  REPLIED
222}
223```
224 
225---
226 
227## API Endpoints
228 
229### Public Endpoints
230 
231| Method | Route | Description |
232|--------|-------|-------------|
233| GET | `/api/properties` | Get all active properties (with filters) |
234| GET | `/api/properties/featured` | Get featured properties (for homepage) |
235| GET | `/api/properties/:id` | Get single property detail |
236| POST | `/api/enquiries` | Submit a property enquiry |
237| POST | `/api/enquiries/general` | Submit a general contact message |
238| POST | `/api/auth/login` | Admin login — returns JWT |
239 
240### Admin Endpoints (JWT required)
241 
242| Method | Route | Description |
243|--------|-------|-------------|
244| GET | `/api/admin/properties` | Get all properties including inactive |
245| POST | `/api/admin/properties` | Create a new property |
246| PUT | `/api/admin/properties/:id` | Update a property |
247| DELETE | `/api/admin/properties/:id` | Delete a property |
248| PATCH | `/api/admin/properties/:id/status` | Toggle active/inactive/sold |
249| GET | `/api/admin/enquiries` | Get all enquiries |
250| PATCH | `/api/admin/enquiries/:id/status` | Update enquiry status |
251 
252### Query Parameters for GET /api/properties
253 
254```
255?type=APARTMENT|HOUSE|VILLA|LAND|COMMERCIAL
256?priceType=SALE|RENT
257?district=Kampala|Wakiso|Mukono|Entebbe
258?minPrice=50000000
259?maxPrice=500000000
260?bedrooms=2
261?featured=true
262?page=1
263?limit=12
264```
265 
266---
267 
268## Pages & Features
269 
270### 1. Home Page (`/`)
271 
272**Sections:**
273- **Hero** — Full-width banner with tagline *"Find Your Place in Uganda"*, a prominent search bar (location + type + price range), and a CTA button "Browse Properties"
274- **Featured Listings** — Grid of 6 featured property cards pulled from the API
275- **Why Glomon Homes** — 3-column trust section: "Verified Listings", "Local Expertise", "Transparent Pricing"
276- **Property Types** — Icon grid: Apartments, Houses, Land, Commercial — each links to filtered listings
277- **Locations We Cover** — Kampala, Wakiso, Entebbe, Mukono, Jinja — with property counts
278- **Testimonials** — 3 static testimonial cards (hardcoded, not from DB)
279- **CTA Banner** — "List Your Property With Us" — links to contact page
280- **Footer** — Logo, links, socials, contact info
281 
282---
283 
284### 2. Listings Page (`/listings`)
285 
286**Features:**
287- Sidebar filters: Property Type, Price Type (Sale/Rent), District, Bedrooms, Price Range
288- Results grid — 12 per page with pagination
289- Sort options: Newest, Price Low-High, Price High-Low
290- Results count displayed ("34 properties found")
291- Each card shows: cover image, title, price, location, bed/bath/area icons, a "View Details" button
292- Empty state with friendly message if no results match filters
293- Loading skeleton cards while fetching
294 
295---
296 
297### 3. Property Detail Page (`/listings/:id`)
298 
299**Sections:**
300- **Image Gallery** — Main image + thumbnail strip, click to expand (lightbox)
301- **Property Header** — Title, price, badge (For Sale / For Rent), status badge
302- **Key Stats Row** — Bedrooms | Bathrooms | Area (sqm) | Property Type
303- **Description** — Full property description text
304- **Amenities** — Icon list of all amenities
305- **Location** — District + address text (no map required for MVP, add later)
306- **Enquiry Form** — Sidebar form: Name, Email, Phone, Message — POST to `/api/enquiries`
307- **Related Properties** — 3 similar properties in the same district
308 
309---
310 
311### 4. About Page (`/about`)
312 
313**Content (static):**
314- Company story — Glomon Homes is a Ugandan property development and real estate listings company founded with a mission to make quality housing accessible and transparent for Ugandans at home and abroad.
315- Mission & Vision statements
316- Team section (placeholder cards — 3 members)
317- Stats row: "200+ Listings", "5 Districts", "Trusted by Buyers Across Uganda"
318 
319---
320 
321### 5. Contact Page (`/contact`)
322 
323**Features:**
324- General contact form: Name, Email, Phone, Subject, Message
325- POST to `/api/enquiries/general`
326- Company contact info: email, phone, physical address (Kampala)
327- Success message on submission
328 
329---
330 
331### 6. Admin Portal (`/admin`)
332 
333**Protected by JWT — redirect to `/admin/login` if not authenticated.**
334 
335**Admin Login (`/admin/login`):**
336- Email + Password form
337- On success → store JWT in localStorage → redirect to dashboard
338 
339**Admin Dashboard (`/admin/dashboard`):**
340- Summary cards: Total Properties, Active Listings, Total Enquiries, New (Unread) Enquiries
341- Quick links to manage properties and view enquiries
342 
343**Admin — Properties (`/admin/properties`):**
344- Table of all properties with columns: Image, Title, Type, Price, District, Status, Actions
345- Actions: Edit, Toggle Status (Active/Inactive/Sold), Delete
346- "Add New Property" button → goes to add form
347 
348**Admin — Add/Edit Property (`/admin/properties/new` and `/admin/properties/:id/edit`):**
349- Form fields: Title, Description, Property Type, Price, Price Type, Currency, Bedrooms, Bathrooms, Area, Location, District, Address, Amenities (checkboxes), Featured toggle, Status
350- Image upload (multiple) via Cloudinary
351- Cover image selector from uploaded images
352- Save / Cancel buttons
353 
354**Admin — Enquiries (`/admin/enquiries`):**
355- Table: Name, Email, Phone, Property (linked), Message preview, Date, Status
356- Click row to expand full message
357- Mark as Read / Replied actions
358 
359---
360 
361## Design Direction
362 
363### Brand Identity
364- **Name:** Glomon Homes
365- **Tagline:** *Find Your Place in Uganda*
366- **Tone:** Professional, warm, trustworthy — not corporate and cold
367- **Feel:** Modern African real estate — clean but with warmth and local character
368 
369### Color Palette
370```css
371--color-primary: #1B4332;      /* Deep forest green — main brand color */
372--color-primary-light: #2D6A4F; /* Lighter green for hover states */
373--color-accent: #D4A017;        /* Gold/amber — for CTAs, highlights */
374--color-accent-hover: #B8860B;  /* Darker gold for hover */
375--color-bg: #F9F6F0;            /* Warm off-white background */
376--color-surface: #FFFFFF;       /* Card surfaces */
377--color-text: #1A1A1A;          /* Primary text */
378--color-text-muted: #6B7280;    /* Secondary/muted text */
379--color-border: #E5E0D8;        /* Subtle borders */
380```
381 
382### Typography
383- **Display / Headings:** `Playfair Display` (Google Fonts) — elegant, authoritative
384- **Body:** `DM Sans` (Google Fonts) — clean, readable, modern
385 
386### UI Principles
387- Generous white space — never crowded
388- Rounded corners: `border-radius: 12px` on cards, `8px` on buttons and inputs
389- Subtle shadows on cards: `box-shadow: 0 2px 16px rgba(0,0,0,0.06)`
390- Green primary buttons with gold accent buttons for secondary CTAs
391- Property cards show a hover lift effect (`transform: translateY(-4px)`)
392- Use badges (pill style) for "For Sale", "For Rent", "Featured"
393 
394---
395 
396## Seed Data
397 
398When running `npx prisma db seed`, populate the database with these sample properties:
399 
4001. **3-Bedroom Apartment in Kololo** — For Sale — UGX 450,000,000 — Kampala — 3 bed / 2 bath / 145 sqm — Amenities: Security, Parking, Generator, Water Tank
4012. **2-Bedroom Flat in Ntinda** — For Rent — UGX 1,800,000/month — Kampala — 2 bed / 1 bath / 90 sqm — Amenities: Security, Parking
4023. **Executive 4-Bedroom House in Muyenga** — For Sale — UGX 850,000,000 — Kampala — 4 bed / 3 bath / 280 sqm — Amenities: Swimming Pool, Security, Parking, Garden, Generator — Featured: true
4034. **Commercial Plot in Namanve** — For Sale — UGX 320,000,000 — Mukono — Land — 0.5 acres
4045. **Modern 2-Bedroom Apartment in Entebbe** — For Sale — UGX 290,000,000 — Wakiso — 2 bed / 2 bath / 110 sqm — Amenities: Security, Parking, Lake View — Featured: true
4056. **Studio Apartment in Bukoto** — For Rent — UGX 900,000/month — Kampala — 1 bed / 1 bath / 45 sqm — Amenities: Security, WiFi Ready
406 
407Use placeholder images from `https://placehold.co/800x600/1B4332/white?text=Glomon+Homes` for all seed properties.
408 
409---
410 
411## Environment Variables
412 
413### Frontend (`frontend/.env`)
414```
415VITE_API_URL=http://localhost:5000
416VITE_CLOUDINARY_CLOUD_NAME=your_cloudinary_cloud_name
417```
418 
419### Backend (`backend/.env`)
420```
421DATABASE_URL=postgresql://postgres:[PASSWORD]@db.[PROJECT].supabase.co:5432/postgres
422JWT_SECRET=your_super_secret_jwt_key_change_this_in_production
423PORT=5000
424CLOUDINARY_CLOUD_NAME=your_cloudinary_cloud_name
425CLOUDINARY_API_KEY=your_cloudinary_api_key
426CLOUDINARY_API_SECRET=your_cloudinary_api_secret
427ADMIN_EMAIL=admin@glomonhomes.com
428ADMIN_PASSWORD=GlomonAdmin2025!
429```
430 
431> The `ADMIN_EMAIL` and `ADMIN_PASSWORD` are used by the seed script to create the first admin user.
432 
433---
434 
435## .gitignore
436 
437```
438node_modules/
439.env
440.env.local
441dist/
442.DS_Store
443*.log
444```
445 
446---
447 
448## Key Rules for Claude Code
449 
4501. **Never hardcode credentials** — always use environment variables
4512. **Always validate inputs** on both frontend (basic) and backend (Zod schemas)
4523. **Handle loading and error states** on every API call in the frontend
4534. **All admin routes must check JWT** via the `authMiddleware` before processing
4545. **Use Prisma client singleton** from `src/lib/prisma.js` — never instantiate it twice
4556. **Price formatting:** Always display prices in UGX with comma separators (e.g. UGX 450,000,000). Use a `formatPrice()` utility in `utils/formatters.js`
4567. **Images:** If no cover image is available, show the placeholder from placehold.co
4578. **Pagination:** Default page size is 12. Always return `{ data, total, page, totalPages }` from paginated endpoints
4589. **CORS:** Configure Express to allow requests from `http://localhost:5173` in development and the Vercel domain in production
45910. **Error responses:** Always return `{ error: "message" }` format from the API — never expose stack traces in production
460 
461---
462 
463## SEO Implementation (applied 2026-04-01)
464 
465### Package
466- `react-helmet-async` installed in `frontend/` — wraps `<App />` with `<HelmetProvider>` in `main.jsx`
467 
468### SEO Component
469- `frontend/src/components/SEO.jsx` — reusable component using `react-helmet-async`
470- Sets `<title>`, meta description, canonical URL, Open Graph tags, and Twitter Card tags
471- Auto-computes canonical from `useLocation()` against `https://glomonhomes.com`
472- Appends `| Glomon Homes` to titles that don't already contain the brand name
473- Accepts: `title`, `description`, `image`, `type`, `noindex` props
474 
475### Per-page SEO
476| Page | Title | Notes |
477|------|-------|-------|
478| HomePage | Glomon Homes \| Buy, Rent & Invest in Uganda Real Estate | + Organization JSON-LD schema (RealEstateAgent) |
479| ListingsPage | Property Listings in Uganda \| Houses, Apartments & Land | H1 updated to "Properties for Sale & Rent in Uganda" |
480| PropertyDetailPage | `{title} in {location}` (dynamic) | + RealEstateListing JSON-LD schema; rendered after property loads |
481| AboutPage | About Glomon Homes \| Uganda's Trusted Real Estate Company | — |
482| ContactPage | Contact Glomon Homes \| Real Estate Enquiries in Uganda | — |
483 
484### Structured Data (JSON-LD)
485- **HomePage:** `RealEstateAgent` schema with address, phone, sameAs social links
486- **PropertyDetailPage:** `RealEstateListing` schema with offer price, address, image
487 
488### index.html changes
489- Updated `<title>` and meta description
490- Added `<meta name="robots" content="index, follow">`
491- Added `<meta property="og:site_name" content="Glomon Homes">`
492- `preconnect` links for Google Fonts already present (kept)
493 
494### Semantic HTML
495- `PropertyCard.jsx`: descriptive `aria-label` on `<Link>`, descriptive `alt` text on `<img>`
496- `HomePage` hero `<section>`: `aria-label="Hero — Find property in Uganda"`
497- Featured section heading updated to "Featured Properties in Uganda"
498- Locations section heading updated to "Properties Across Uganda"
499 
500### robots.txt
501- `frontend/public/robots.txt` — allows all, disallows `/admin`, references sitemap
502 
503### Sitemap
504- `GET /sitemap.xml` endpoint in `backend/src/index.js`
505- Queries all `ACTIVE` properties from the database
506- Returns valid XML sitemap with static pages + per-property URLs
507- Property `lastmod` derived from `updatedAt`
508 
509### Vite build optimisation
510- `frontend/vite.config.js` updated with `manualChunks` splitting `vendor` (react, react-dom, react-router-dom) and `ui` (lucide-react, axios)