Realtor Platform

A comprehensive real estate CRM platform built with Next.js, featuring multi-tenant federation, client management, property listings, testimonials, and appointment scheduling.

Tech Stack

• Framework: Next.js 16 with App Router
• Database: PostgreSQL with Prisma ORM
• Authentication: NextAuth.js (Credentials + OAuth/OIDC)
• Styling: Tailwind CSS + Materialize CSS (legacy components)
• Deployment: Docker containerized

Features

Client Portal

• Shared Listings: View properties shared by the realtor
• Appointment Scheduling: Book appointments (via Nextcloud Calendar integration)
• Preferences: Set budget, preferred areas, property types
• Testimonials: Submit and manage client testimonials
• Privacy: Export or delete all personal data

Admin Dashboard

• Client Management: Track clients through pipeline (NEW → CONTACTED → ACTIVE → INACTIVE → CLOSED)
• Listing Management: Create/edit listings with multiple photos, cover photo selection
• Listing Sharing: Share listings with specific clients
• Testimonial Moderation: Approve/reject client testimonials, feature on homepage
• Federation: Connect with other realtor sites to share listings
• Showing Requests: Manage property showing requests from federated sites
• Settings: Configure SMTP, Nextcloud, appointment scheduling URLs

Public Pages

• Homepage: Featured listings, testimonials, contact form
• Listings: Browse available properties
• Testimonials: View approved client testimonials
• Contact: Submit inquiries (with Friendly Captcha)

Federation System

• Multi-tenant: Share listings across realtor sites
• Trust Scoring: Rate and review federated partners
• API Key Rotation: Secure key management with expiration
• Showing Requests: Request property showings from federated sites

Project Structure

src/
├── app/
│   ├── (public)/           # Public-facing pages
│   │   ├── page.tsx        # Homepage
│   │   ├── about/
│   │   ├── contact/
│   │   ├── listings/
│   │   └── testimonials/
│   ├── (admin)/           # Admin dashboard
│   │   └── admin/
│   │       ├── page.tsx    # Dashboard
│   │       ├── clients/
│   │       ├── listings/
│   │       ├── testimonials/
│   │       ├── federation/
│   │       ├── federation-showings/
│   │       ├── messages/
│   │       ├── pages/
│   │       └── settings/
│   ├── (client)/          # Client portal
│   │   └── client/
│   │       ├── page.tsx    # Dashboard
│   │       ├── listings/
│   │       ├── preferences/
│   │       ├── appointments/
│   │       ├── testimonials/
│   │       └── privacy/
│   ├── api/               # API routes
│   │   ├── admin/         # Admin-only endpoints
│   │   ├── client/        # Client portal endpoints
│   │   ├── federation/    # Federation API
│   │   └── uploads/       # File uploads
│   ├── login/
│   ├── register/
│   ├── client-login/
│   └── client-register/
├── components/
│   ├── ui/                # UI primitives (Button, Card, Input, etc.)
│   ├── theme/             # Dark/light mode
│   └── ...
├── lib/
│   ├── auth.ts            # NextAuth configuration
│   ├── prisma.ts          # Prisma client
│   └── federation.ts       # Federation utilities
└── styles/
    └── globals.css        # Global styles + dark mode

prisma/
├── schema.prisma          # Database schema
└── seed.ts               # Seed data

docker-compose.yml         # Docker configuration

Database Schema

Core Models

• User: Authentication accounts (admin and clients)
• Client: Client profiles with preferences
• Listing: Property listings with images
• ListingShare: Links listings to clients
• Appointment: Scheduled appointments
• Testimonial: Client testimonials with approval workflow
• ContactMessage: Contact form submissions
• Page: Public page content (title, subtitle, headshot)
• Setting: Key-value settings (SMTP, Nextcloud, etc.)

Federation Models

• FederationConnection: Connected federation sites
• FederationApiCall: API call logs
• FederationFeedback: Trust feedback between sites
• ShowingRequest: Showing requests from federated sites

Architecture

Authentication

• NextAuth.js with Credentials provider for email/password
• OAuth/OIDC support for Google, Microsoft, Facebook, Authentik, Keycloak
• Role-based access: Admin vs Client

API Design

• RESTful endpoints under /api/
• Admin routes require admin session
• Client routes require client session
• Federation routes require API key authentication

Dark Mode

• Tailwind CSS custom variants
• CSS variables for theming
• Inline script for flash-of-unstyled-content prevention
• Comprehensive Materialize CSS overrides

Getting Started

Prerequisites

• Node.js 20+
• PostgreSQL 14+
• Docker (optional)

Installation

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Configure .env with your database and secrets

# Generate Prisma client
npx prisma generate

# Push schema to database
npx prisma db push

# Seed database (optional)
npm run seed

# Start development server
npm run dev

Docker

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f app

# Access database
docker-compose exec db psql -U postgres -d realtor

Configuration

Environment Variables

# Database
DATABASE_URL="postgresql://user:pass@localhost:5432/realtor"

# NextAuth
NEXTAUTH_SECRET="your-secret-key"
NEXTAUTH_URL="http://localhost:3000"

# Email (SMTP)
SMTP_HOST="smtp.example.com"
SMTP_PORT="587"
SMTP_USER="user@example.com"
SMTP_PASS="password"

# Nextcloud Calendar (optional)
NEXTCLOUD_URL="https://cloud.example.com"
NEXTCLOUD_USERNAME="admin"
NEXTCLOUD_APP_PASSWORD="app-password"

# Friendly Captcha (optional)
FRIENDLY_CAPTCHA_SITE_KEY=""
FRIENDLY_CAPTCHA_SECRET_KEY=""

# OAuth Providers (optional)
AUTH_GOOGLE_ID=""
AUTH_GOOGLE_SECRET=""
AUTH_MICROSOFT_ENTRA_ID_CLIENT_ID=""
AUTH_MICROSOFT_ENTRA_ID_CLIENT_SECRET=""

Admin Setup

1. Register at /register or use seeded admin: admin@realtor.local / admin123
2. Configure SMTP at /admin/settings for email notifications
3. Set up Nextcloud for appointment scheduling (optional)
4. Configure appointment scheduling URL for clients

Accessibility (WCAG 2.1 AA)

The platform follows accessibility best practices:

• Contrast: 4.5:1+ ratio for text, 3:1+ for focus indicators
• Keyboard: Full keyboard navigation with visible focus
• Screen Readers: Proper ARIA labels, roles, and live regions
• Forms: Associated labels, required field indicators, error messages

Key Accessibility Features

• Skip navigation links
• Semantic HTML (nav, main, section, article)
• Form validation with aria-invalid and aria-describedby
• Status badges with icons + text (not color alone)
• Alt text for images

Quality Assurance

Commands

npm run lint          # ESLint
npm run build         # Production build
npm run test         # Jest tests
npm run test:api     # API tests only
npm audit            # Security audit

Security

• API routes enforce authentication
• Public endpoints only return public data
• Input validation and sanitization
• No secrets in logs or error messages

Test Accounts

• Admin: admin@realtor.local / admin123
• Client: testclient@test.com / client123

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

See LICENSE for the full license text.

Summary of GPL-3.0 Permissions

• Commercial use allowed
• Modification allowed
• Distribution allowed
• Patent use allowed
• Private use allowed

Key Obligations

• Source code must be made available when distributing
• Changes must be documented
• License and copyright notices must be preserved
• Same license must be applied to derivatives