> AI-powered property recommendation engine with persona-based scoring and intelligent multi-source data enrichment, with additional video output

Domus is an intelligent property recommendation system that helps users find the perfect London neighborhood based on their lifestyle and priorities. The platform leverages a sophisticated 3-layer AI orchestration architecture to synthesize live data from property intelligence APIs, transport networks, crime statistics, and education ratings—delivering personalized, data-driven area recommendations with transparent scoring and AI-generated explanations and tiktok output

Target Users:

• Students seeking affordable areas with good transport links to universities.
• Parents prioritizing school quality, safety, and family-friendly neighborhoods.
• Property Developers looking for investment opportunities with high ROI potential.
• Climate warrior seeking eco-friendly neighborhoods with green spaces and sustainable living options "coming soon" because of lack of data available from ScanSan’s API

• Features
• Tech Stack
• Architecture Overview
• Installation
• Usage
• Configuration
• Screenshots / Demo
• API / CLI Reference
• Tests
• Roadmap
• Contributing
• License
• Contact / Support

• 🎯 Persona-Driven Scoring - Customized ranking algorithms for Students, Parents, and Property Developers with tailored factor weights.
• 🏘️ Multi-Source Data Enrichment - Integrates ScanSan property intelligence, TfL transport data, UK Police crime statistics, and Ofsted school ratings.
• 🤖 AI-Powered Explanations - Natural language justifications for every recommendation using Claude AI.
• 📊 Transparent Factor Breakdown - Clear visibility into affordability, commute, safety, amenities, and investment quality scores.
• ⚡ Real-Time Analysis - Live API calls ensure up-to-date property market data.
• 🔄 Self-Annealing Architecture - Automatically diagnoses and fixes API failures within the orchestration layer.

• Frontend: Next.js 14 (App Router), TypeScript, Tailwind CSS
• Backend: Python 3.11+ (Data Processing), Node.js (API Layer), Anthropic Claude API (Orchestration)
• Data Pipeline: Pandas, NumPy, aiohttp (Async I/O)
• Cache & Infrastructure: Redis, Modal (Python Serverless), Vercel
• Testing: Jest, Playwright, Pytest

graph TB
    User["👤 User Interface/API"] --> Orchestrator["🧠 Layer 2: AI Orchestrator<br/>(Claude LLM)"]
    Orchestrator --> Directives["📋 Layer 1: Directives<br/>(Markdown SOPs)"]
    Orchestrator --> ScanSan["🏘️ ScanSan Script"]
    Orchestrator --> TfL["🚇 TfL Script"]
    Orchestrator --> Crime["🚔 Crime Data Script"]
    Orchestrator --> Schools["🏫 Schools Script"]
    Orchestrator --> Video["🎬 Video Generator"]
    
    ScanSan --> ScanSanAPI["ScanSan Property API"]
    TfL --> TfLAPI["TfL Unified API"]
    Crime --> PoliceAPI["UK Police Data API"]
    Schools --> GIAS["GIAS/Ofsted API"]
    Video --> VideoAI["Domus/Sora/LTX API"]
    
    ScanSan --> Cache["⚡ Redis Cache"]
    TfL --> Cache
    Crime --> Cache
    Schools --> Cache
    
    style User fill:#e1f5ff
    style Orchestrator fill:#fff4e1
    style Directives fill:#f0f0f0
    style Cache fill:#ffe1e1
    
    subgraph "Layer 3: Execution Workers"
        ScanSan
        TfL
        Crime
        Schools
        Video
    end
    
    subgraph "External APIs"
        ScanSanAPI
        TfLAPI
        PoliceAPI
        GIAS
        VideoAI
    end

1. User Request: Provides persona, budget, destination, and preferences
2. Orchestration: Claude reads MASTER_ORCHESTRATION.md to determine workflow
3. Parallel Fetching: Triggers Layer 3 scripts simultaneously to fetch data from multiple APIs
4. Caching: Redis checks for cached results to minimize API calls and reduce latency
5. Scoring: Persona-specific weights applied to raw data (e.g., Students: 40% affordability, 30% commute, 20% amenities, 10% safety)
6. Ranking: Areas sorted by weighted scores
7. Synthesis: Claude generates natural language explanations for top recommendations
8. Delivery: Ranked list with transparent scoring breakdown returned to user

• Flexibility: Business logic updates via Markdown directives without code changes
• Reliability: Deterministic execution layer ensures consistent data processing
• Self-Healing: Orchestrator can diagnose failures and retry with alternative strategies
• Transparency: Every recommendation includes explainable scoring factors
• Scalability: Parallel execution and aggressive caching support concurrent users
• Maintainability: Clear separation of concerns across three distinct layers

For detailed architecture diagrams and technical specifications, see ARCHITECTURE.md.

1. Clone the Repository:

   git clone https://github.com/younis-y/RealTech-Hackathon.git
   cd RealTech-Hackathon

2. Backend Setup (Python):

   python -m venv venv
   source venv/bin/activate  # venv\Scripts\activate on Windows
   pip install -r requirements.txt

3. Frontend Setup (Node.js):

   cd frontend
   npm install

Start the development server and visit http://localhost:3000:

cd frontend
npm run dev

Run the complete recommendation pipeline from the command line:

python demo_pipeline.py --persona student --budget 1200 --type rent --destination UCL

Create a .env file in the project root:

# Required API Keys
SCANSAN_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
TFL_API_KEY=your_key_here

# Caching
REDIS_URL=redis://localhost:6379

<!-- Placeholder for project screenshots -->

Live Demo: https://github.com/younis-y/RealTech-Hackathon

POST /api/recommendations

{
  "persona": "student",
  "budget": 1200,
  "locationType": "rent",
  "destination": "UCL"
}

Area Data Fetcher

python execution/scansan_api.py E1 SW1A N7

cd frontend
npm test
npm run test:e2e

pytest

• Phase 1: Core 3-Layer Architecture
• Phase 2: Modal Serverless & Redis Deployment
• Phase 3: Real-time Rental Listing Integration (Rightmove/Zoopla)
• Phase 4: AI-Generated Video Explainers with Narration

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

This project is licensed under the MIT License - see the LICENSE file for details.

Maintainer: Younis Y GitHub: @younis-y Project Link: https://github.com/younis-y/RealTech-Hackathon