📐 Platform Blueprint

UnitCycle Complete Platform Blueprint

End-to-end documentation of every workflow, data flow, and system interaction in the UnitCycle Real Estate Intelligence Platform — from property onboarding through the entire tenant lifecycle, maintenance operations, financial management, and AI-powered intelligence.

Routes 90+
Services 76
Models 100+
Django Apps 35
Portals 4
AI Features 12

Table of Contents

1 System Overview & Architecture 2 Property Onboarding 3 Unit Lifecycle & Status Management 4 Leasing Pipeline (Vacant → Leased) 5 Tenant Lifecycle 6 Maintenance & Work Orders 7 Financial Management 8 Multi-Portal Architecture 9 AI-Powered Features 10 Data Model & Relationships 11 API Reference 12 Tech Stack & Infrastructure
1

System Overview & Architecture

UnitCycle is a B2B2C rental property management intelligence platform. It connects Property Managers, Tenants, Owners, and Vendors through dedicated portals, powered by a Django REST API backed by PostgreSQL with Yardi-synced data.

The Grand Scheme — Complete Platform Flow

🏢 Add Property → 🏗 Add Buildings → 🚪 Add Units → 📋 Mark Vacant → 📡 Syndicate Listing → 📅 Schedule Showings → 📝 Receive Applications → 🔍 AI Screening → ✅ Approve Applicant → 📄 Generate Lease → ✍️ Sign Lease (DocuSign) → 🔎 AI Lease Abstraction → 🏠 Move-In Inspection → 📋 Onboarding Checklist → 👤 Active Tenant → 💰 Rent Payments → ⚠️ Delinquency → 📞 Collections → 🔄 Renewal / Notice → 📸 Move-Out Inspection → 🔧 Turnover / Make Ready → 📋 Back to Vacant

Three-Actor Model

UnitCycle serves three primary actors in rental property management, each with their own portal and workflows.

🏢 Property Manager (PM)

The primary user — manages everything
  • Full dashboard with portfolio KPIs
  • Property, building, and unit management
  • Tenant lifecycle management
  • Work order creation and oversight
  • Financial management and invoicing
  • AI-powered intelligence tools
  • Owner reporting and communication
  • Vendor directory and performance tracking

👤 Tenant

Self-service portal for residents
  • View lease details and documents
  • Make rent payments (Stripe integration)
  • Submit and track maintenance requests
  • Chat with property management
  • View payment history and balance
  • Set up autopay enrollment
  • Upload documents and view notices

🔧 Vendor / Technician

Maintenance portal + marketplace
  • Mobile-first PWA for field technicians
  • Work order management with GPS tracking
  • Photo capture and completion checklists
  • VendorHub marketplace for bidding on jobs
  • Invoice upload after work completion
  • Schedule management and time logging
  • Offline support with IndexedDB sync

System Architecture

Frontend
Angular 19 SPA → Standalone Components → Signals State → Lazy Routes → TailwindCSS
API Layer
Django REST Framework → ViewSets + Routers → ModelSerializers → JWT Auth
Database
PostgreSQL 17 → 147 Tables → Yardi-synced (managed=False) → Companion Tables
AI Layer
OpenRouter API → Gemini Flash → Lease Generation → Portfolio Chat → Screening Scores
Infra
Contabo VPS → Nginx Reverse Proxy → PM2 Process Manager → Let's Encrypt SSL
2

Property Onboarding

Everything starts with adding a property to the portfolio. Properties contain buildings, buildings contain units. This hierarchical structure is the foundation of all operations.

Property → Building → Unit Hierarchy

🏢 Create Property → 📍 Set Address & Details → 🏗 Add Buildings → 🚪 Add Units per Building → 📊 Property Goes Live
Backend

Property Data Model

Properties table — Yardi-synced (managed=False)
  • property_code — Unique identifier from Yardi
  • name — Display name (e.g., "The Residences at Marina")
  • address_line1, city, state, postal_code — Location
  • total_units — Unit count for the property
  • current_value — Property valuation
  • annual_taxes — Tax burden
  • latitude, longitude — GPS for map display
  • property_class — A, B, C classification
  • status — active, inactive, pending
  • features — JSON blob of amenities
Frontend

Property Management UI

Route: /property-management
  • Portfolio Grid — Card layout with 4-KPI strip (Units | Revenue | Occupancy | Exposure)
  • Property Detail → KPI cards + Honeycomb hex grid of units
  • Building Detail → Dense Color Rack layout (10-col grid)
  • Unit Detail → Tenant info, lease, maintenance, financials
  • Portfolio Map — Leaflet + CARTO Dark Matter with gold dots
  • Search & Filter — By status, class, city, manager
Backend

Building Data Model

PropertiesBuilding — child of Properties
  • name — Building name (e.g., "Barn A")
  • building_number — Sequential ID
  • floors — Number of floors
  • total_units — Units in this building
  • amenities — JSON array of building amenities
  • FK → Properties — Parent property link
Backend

Unit Data Model

UnitsUnit — the atomic rentable entity
  • unit_number — Display number (e.g., "A-101")
  • bedrooms / bathrooms — Unit specs
  • square_feet — Size
  • market_rent / current_rent — Pricing
  • status — occupied, vacant, maintenance, notice
  • FK → Building and FK → Properties

What Happens After Property Is Created

Once a property exists in the system, several features activate automatically:

📊 Dashboard Integration

  • Property appears on portfolio dashboard
  • KPIs start calculating (occupancy, revenue, exposure)
  • Map pin placed at GPS coordinates
  • Property heatmap visualization updates

🏠 Owner Assignment

  • Eigentümer (Owner) linked via EigentuemerLiegenschaft
  • Ownership percentage (anteil_prozent) set
  • Owner portal access enabled
  • Revenue sharing calculations begin

📋 Insurance & Compliance

  • Insurance compliance tracking activates
  • Policy lapse monitoring begins
  • Legal override framework available
  • BK anomaly detection initialized

🔧 Maintenance Readiness

  • IoT sensor assignment possible
  • Asset registry initialized
  • Predictive maintenance model starts
  • Work order routing configured
3

Unit Lifecycle & Status Management

Every unit cycles through distinct statuses. The Lifecycle Dashboard tracks every unit across the portfolio and provides the PM with actionable intelligence on transitions.

Unit Status Lifecycle

🚪
Vacant / Make Ready
📡
Listed / Syndicated
📝
Application Received
📄
Lease Pending
✅
Leased / Occupied
📋
Month-to-Month
⚠️
Notice Given
🔧
Turnover / Make Ready

Lifecycle Dashboard

The central command center for tracking every lease status transition across the portfolio.

PM Actions
View all leases by status → Filter by property/building → Convert to MTM → Give Notice → Mark Vacant
System
Auto-detect expired leases → Transition to holdover → Log status change → Update lifecycle record
AI Engine
Calculate churn risk → Predict turnover timeline → Revenue impact analysis

TenantLeaseLifecycle Model

Companion table tracking lease status transitions
  • lease_status — active, expired, holdover, notice, vacated, renewed
  • status_changed_at / by — Audit trail
  • holdover_start_date — When MTM began
  • notice_date — When notice was given
  • notice_move_out_date — Expected move-out
  • actual_move_out_date — Real move-out

LeaseStatusLog Model

Every status change is logged permanently
  • previous_status → new_status — The transition
  • changed_by — Who made the change
  • reason — Why (free text)
  • metadata — JSON context data
  • Enables full audit trail of every lease
  • Powers the lifecycle timeline visualization
4

Leasing Pipeline — Vacant to Leased

The most critical workflow in the platform. When a unit becomes vacant, a multi-step pipeline activates to fill it as fast as possible with the best tenant — from listing through to signed lease.

Complete Leasing Pipeline Flow

📋 Unit Vacant → 📸 Virtual Staging → 📡 Syndication → 📅 Smart Showings → 📝 Applications → 🔍 AI Screening → ✅ Approval → 📄 Lease Generation → ✍️ DocuSign → 🔎 Abstraction

Step 1: Virtual Staging (AI)

AI-powered room staging to make vacant units look furnished and appealing for listings.

AI Feature

How It Works

  • PM uploads photos of empty rooms
  • Selects style (modern, traditional, minimalist, etc.)
  • AI generates staged versions of each photo
  • PM reviews, approves, or regenerates
  • Approved photos publish directly to listings
Backend

Data Model

  • StagingProject — FK → Unit, style, status, listing text
  • StagingPhoto — room, original_url, staged_url, AI description
  • Route: /virtual-staging
  • API: /api/v1/staging/projects/

Step 2: Listing Syndication

Push listings to multiple platforms simultaneously with AI-optimized descriptions and pricing.

Frontend

Syndication Dashboard

  • Create listing with unit details + staged photos
  • AI-optimized title and description generation
  • SEO score calculation for listing quality
  • Multi-platform publish (Zillow, Apartments.com, etc.)
  • Stale listing detection (days_listed tracker)
  • AI-powered repricing based on market data
Backend

Lead Management

  • SyndicationListing — unit, platforms(JSON), photos(JSON), seo_score
  • SyndicationLead — prospect info, platform source, AI grade, suggested_response
  • Leads graded A/B/C/D with AI scoring
  • Auto-suggested responses for each lead
  • Route: /syndication

Step 3: Smart Showings

Schedule and manage property tours with AI-powered no-show risk prediction.

AI Feature

Showing Intelligence

  • Schedule self-guided or accompanied tours
  • Identity verification before access code generation
  • AI predicts no-show risk (score + level + factors)
  • Automated reminder sending based on risk level
  • Post-showing feedback collection (rating, liked/disliked, price perception)
  • AI theme extraction from feedback for listing improvement
  • Conversion funnel tracking (showing → application)

Step 4: Tenant Screening (AI)

AI-powered applicant evaluation with rules-based scoring and risk assessment.

Applicant
Submit application → Provide income, rental history, credit info
AI Engine
Calculate ai_score (0-100) → Component scores (income, credit, rental, employment) → Risk factors identification → Approve / Conditional / Deny recommendation
PM Review
Review AI recommendation → Override if needed → Approve or Deny

ScreeningApplication Model

  • Applicant Profile — name, email, phone, current_address, employer
  • Financial — annual_income, credit_score, monthly_debt
  • Rental History — previous_landlord, years_renting, eviction_history
  • AI Scoring — ai_score (0-100), recommendation (approve/conditional/deny)
  • Component Scores — income_score, credit_score, rental_score, employment_score
  • risk_factors — JSON array of identified risks
  • Status Flow — submitted → under_review → approved / denied

Step 5: AI Lease Generation

Three-step wizard that generates a complete lease document with AI-powered clause selection.

Lease Generation Wizard

Step 1: Deal Terms → Step 2: Configure Clauses → Step 3: Generate & Review → DocuSign Signing

Step 1: Deal Terms

  • Select unit and tenant
  • Set monthly rent and security deposit
  • Choose lease start/end dates
  • Set jurisdiction (state law compliance)
  • Rent escalation percentage

Step 2: Configure Clauses

  • 15 clause types available (8 required, 7 optional)
  • Each clause has configurable parameters
  • AI suggests clause language based on jurisdiction
  • Required: Rent, Deposit, Term, Use, Entry, Maintenance, Insurance, Default
  • Optional: Pets, Parking, Smoking, Subletting, Late Fees, Utilities, Renewal

Step 3: Generate & Sign

  • AI generates complete PDF via ReportLab
  • PDF preview with iframe viewer
  • Risk score calculation per clause
  • DocuSign simulation for electronic signatures
  • Signature request tracking (signer_email, token, ip_address)
Backend

GeneratedLease Model

  • FK → Unit, Property
  • tenant_name, monthly_rent, deposit, dates
  • clauses (JSON) — full clause configuration
  • addenda (JSON) — additional documents
  • pdf_url — generated document location
  • overall_risk_score — AI compliance risk
  • Status: draft → generated → sent → signed → active

Step 6: AI Lease Abstraction

After a lease is signed, AI extracts and validates all key terms from the PDF document.

AI Feature

What Gets Extracted

  • Core Terms — tenant_name, lease dates, monthly_rent, security_deposit
  • Policies — pet_policy, parking details
  • Clauses — JSON array of all lease clauses with text
  • Non-Standard Clauses — AI flags unusual terms for PM review
  • source_lease_id — Links back to GeneratedLease
  • Confirm → Apply — PM reviews extraction, confirms, then applies to lease record
  • Uses @xframe_options_sameorigin for PDF iframe display
5

Tenant Lifecycle

Once a lease is signed, the tenant enters the system. This section covers every stage from move-in through ongoing tenancy to eventual move-out and turnover.

Complete Tenant Journey

🏠 Move-In Inspection → 📋 Onboarding Checklist → 🔑 Key Issuance → 👤 Active Tenant → 💰 Rent Payments → ⚠️ Delinquent? → 📞 Collections → 🔄 Renewal Decision → 📸 Move-Out Inspection → 🔧 Turnover

Phase 1: Move-In Inspection

Document unit condition before tenant occupancy. Creates the baseline for move-out comparison.

Inspection Process

  • Inspector creates inspection for the unit
  • Room-by-room walkthrough (kitchen, bedroom, bathroom, etc.)
  • Photo capture with GPS coordinates and timestamps
  • AI quality score for each photo (is_acceptable check)
  • AI auto-detects items in photos (items_found JSON)
  • Checklist items per room with condition ratings
  • Completeness percentage tracked automatically
  • Both tenant and PM sign off digitally
  • PDF report generated automatically

Data Captured

  • MoveInInspection — unit, property, inspector, tenant, status
  • MoveInRoom — room_type, overall_condition, checklist_items(JSON)
  • MoveInPhoto — photo_url, GPS, ai_quality_score, ai_items_found
  • Status flow: scheduled → in_progress → completed → signed

Phase 2: Tenant Onboarding

Structured checklist ensuring new tenants complete all move-in tasks.

Onboarding Checklist Tasks

  • 📄 Sign lease documents
  • 💰 Pay security deposit and first month rent
  • 🔑 Key collection and access setup
  • ⚡ Utility transfers (gas, electric, internet)
  • 🐾 Pet registration (if applicable)
  • 🅿️ Parking assignment
  • 📦 Storage assignment
  • 📋 Renter's insurance upload
  • 📱 Download tenant portal app
  • 🚨 Emergency contact information

System Features

  • Stall Detection — AI identifies stuck onboardings
  • AI Chat — Tenant can ask questions about the process
  • Utility Guide — Auto-generated guide for the area
  • Key Issuance — Track keys (type, identifier, issued_to, returned)
  • completion_pct — Real-time progress tracking
  • Status: not_started → in_progress → completed

Phase 3: Active Tenancy

Day-to-day tenant management — payments, maintenance, communications, and insurance.

💰 Rent Payments

  • Monthly rent charge via recurring_charges
  • Tenant pays through portal (Stripe integration)
  • Payment methods: credit card, bank ACH
  • Autopay enrollment available
  • Every transaction logged in tenant_ledger_entry
  • Balance tracking (open charges vs payments)

🔧 Maintenance Requests

  • Tenant submits via portal with photos
  • PM triages and assigns to vendor
  • Full work order lifecycle (see Section 6)
  • Real-time status updates to tenant
  • In-app messaging between tenant and PM

📋 Lease Management

  • Lease details visible to tenant in portal
  • Occupant management (roommates, guarantors)
  • Pet registry with breed/weight tracking
  • Emergency contact management
  • Employment verification records

💬 Communications

  • Tenant can chat with PM through portal
  • AI message classification and urgency detection
  • Emergency detection triggers immediate alert
  • Broadcast messaging for property-wide notices
  • Sentiment tracking per tenant (churn risk)

Phase 4: Delinquency & Collections

When tenants don't pay, the AI-powered collections engine activates — escalating from friendly reminders to legal action.

Collections Escalation Ladder

Day 1: Friendly Reminder → Day 3: Follow-up SMS → Day 7: Phone Call → Day 14: Payment Plan Offer → Day 21: Formal Demand → Day 30: Legal Notice → Day 45+: Attorney Referral

CollectionCase Model

~80 fields tracking every aspect of delinquency
  • Balance tracking — total_balance, days_overdue
  • Escalation — escalation_level (1-5), risk profile
  • Communication tone — friendly, firm, urgent, legal
  • SCRA/Bankruptcy flags — Legal protections check
  • TCPA compliance — Call/text consent tracking
  • AI predictions — payment_probability, best_contact_time
  • Payment Plans — installments with tracking
  • Legal Events — court_date, filing_date, hearing status

Collection Actions

  • Automated SMS/email based on escalation level
  • AI-generated message templates per stage
  • Phone call logging with outcome tracking
  • Payment plan creation with installment tracking
  • Document generation (demand letters, legal notices)
  • Attorney referral with legal fee tracking
  • Full audit trail of every action taken

Phase 5: Renewal Intelligence

AI-powered lease renewal recommendations with churn prediction and rent optimization.

AI Engine
Scan expiring leases → Calculate churn score → Market rent comparison → Generate recommendation
PM Review
Review recommendation → Approve / modify terms → Generate renewal letter → Send to tenant
Tenant
Receive offer → Accept / Negotiate / Decline

RenewalRecommendation Model

  • churn_score — Probability of tenant leaving (0-100)
  • churn_risk_level — low, medium, high
  • churn_factors — JSON array of contributing factors
  • current_rent vs market_rent — Gap analysis
  • recommended_rent — AI-optimized price
  • rent_strategy — match_market, below_market, aggressive
  • recommended_term — Suggested lease length
  • Status: pending → approved → sent → accepted/declined

Phase 6: Move-Out & Turnover

When a tenant leaves — inspect the unit, calculate deductions, and prepare for the next tenant.

Turnover Pipeline (Kanban Board)

📋 Notice Received → 📸 Move-Out Inspection → 💰 Deposit Reconciliation → 🔧 Make Ready → ✅ Ready to Lease → 📡 Re-Listed

Move-Out Inspection

  • Compare current condition vs move-in photos
  • AI damage detection from photos
  • Severity classification (minor, moderate, severe)
  • Deduction amount calculation per item
  • Adjusted amount after PM review
  • Deduction letter generation
  • Deposit refund calculation

Turnover Case Model

  • Stage — notice → inspection → deposit_reconciliation → make_ready → ready_to_lease → leased
  • Key Dates — notice, move_out, inspection, make_ready, listed, leased
  • Costs — deposit held, deductions, refund, make_ready_cost
  • Checklist — Configurable tasks per stage
  • Turnover Log — Every stage transition logged
6

Maintenance & Work Orders

Work orders flow through a complete lifecycle from creation to completion, involving PMs, tenants, technicians, and vendors. UnitCycle tracks 10 different work order sources and provides AI-powered predictive maintenance.

Work Order Lifecycle

📝 Created → 🔍 Triaged → 📡 Posted to Marketplace → 💼 Vendor Bids → ✅ Bid Awarded → 📅 Scheduled → 🔧 In Progress → ✅ Completed → 📝 Tenant Sign-off → 💰 Invoice & Close

Work Order Sources (10 Channels)

Request Sources

  • 🏠 Tenant Portal — Self-service maintenance request
  • 👤 PM Created — Property manager initiates
  • 📱 Phone/Walk-in — Traditional request
  • 📧 Email — Parsed from tenant email
  • 📸 Move-In/Out Inspection — Issues found during inspection
  • 🤖 IoT Sensor Alert — Automated from sensor readings
  • 🔮 Predictive Maintenance — AI-predicted failure
  • 📋 Preventive Schedule — Calendar-based PM schedule
  • ⚖️ Legal/Compliance — Required by regulation
  • 🔧 Turnover Make-Ready — Post-move-out repairs

WOSource Tracking

Companion table tracking origin of every WO
  • source_channel — Which of the 10 sources
  • triggered_by_type/id/name — Who or what created it
  • equipment_name / asset_name — Related equipment
  • source_metadata — JSON context from source
  • IoTWorkOrderSource — extra detail for sensor-triggered WOs

VendorHub Marketplace

When a work order needs an external vendor, it's posted to the marketplace for competitive bidding.

PM
Create marketplace job → Set budget range → Review bids → Award bid
Vendor
Browse available jobs → Submit bid → Win award → Schedule work → Complete & invoice
Tenant
Set availability → Confirm schedule → Grant entry permission → Sign-off on completion

IoT & Predictive Maintenance

🌡️ IoT Sensors

  • Temperature, humidity, water leak, HVAC, electrical sensors
  • Configurable thresholds with alert priorities
  • Real-time readings with anomaly detection
  • Auto-creates work order when threshold exceeded
  • SVG gauge visualization on equipment detail

🔮 Predictive Maintenance

  • Equipment inventory with lifecycle tracking
  • AI maintenance predictions with confidence scores
  • Risk scoring per unit (factor breakdown)
  • Preventive work order suggestions
  • Preventive maintenance schedules (frequency-based)
  • Asset health dashboard with 3 tabs
7

Financial Management

UnitCycle provides comprehensive financial tracking — from invoice processing to revenue intelligence, operating cost analysis, and owner reporting.

📄 Invoice Processing Pipeline

  • Scan — Upload invoice PDFs (base64)
  • AI Extraction — Auto-extract vendor, amounts, dates, line items
  • Duplicate Detection — AI pattern matching for duplicate invoices
  • Vendor Matching — Auto-match to vendor directory
  • GL Code Assignment — Chart of accounts mapping
  • Exception Queue — Manual review for edge cases
  • Approval — PM approves extraction results
  • PDF Split — Split multi-invoice PDFs into individual invoices

📊 Revenue Intelligence

  • Pricing Snapshots — current vs market vs recommended rent per unit
  • Rent Gap Analysis — $ and % below/above market
  • Market Comps — Comparable units from market data
  • Confidence Scoring — How reliable is the recommendation
  • Accept/Reject — PM acts on pricing recommendations
  • Route: /revenue

💰 Tenant Ledger

  • Every financial transaction recorded in tenant_ledger_entry
  • trans_type — charge, payment, credit, adjustment
  • charge_code — Rent, Late Fee, Utility, etc.
  • is_open — Unpaid balance tracking
  • 50K+ ledger entries in demo database
  • Powers payment history and balance calculations

📈 Analytics Dashboard

  • Overview Tab — Portfolio-wide KPIs, Yardi stats
  • Finance Tab — Budget performance, cash flow, expense distribution, vendor expenditures
  • Vendor Tab — Payment behavior analysis, performance metrics
  • Date range filtering for period comparison
  • ApexCharts visualizations throughout

🇦🇹 BK Anomaly Detection (Austrian)

  • Betriebskosten (operating cost) anomaly detection
  • Year-over-year comparison per category
  • Deviation calculation (% and € amount)
  • Severity classification (minor, moderate, major)
  • AI explanation of detected anomalies

🏦 Reserve Fund Management (Austrian)

  • Rücklage (reserve fund) tracking per property per year
  • Legal minimum per m² calculation
  • Soll (target) vs Ist (actual) contributions
  • Transaction history (Einzahlung, Auszahlung, Zinsen)
  • Account balance tracking

Owner Financial Reporting

Property owners (Eigentümer) get comprehensive financial visibility into their investments.

Owner Detail — 6 URL-Mapped Tabs

  • /owners/:id/overview — Portfolio summary, ownership percentages
  • /owners/:id/financials — Revenue via raw SQL (tenants.unit_id unmapped), expenses, NOI
  • /owners/:id/properties — All properties with ownership stake
  • /owners/:id/tenants — All tenants across owned properties
  • /owners/:id/work-orders — Maintenance activity
  • /owners/:id/reserves — Reserve fund balances and transactions
8

Multi-Portal Architecture

UnitCycle serves different users through dedicated portals, each with its own authentication, UI, and feature set.

🏢 Property Manager Portal
📊 Full Dashboard with Portfolio KPIs
🏢 Property/Building/Unit Management
👤 Tenant Management (CRUD + Detail)
🔧 Work Order Management
💰 Financial Management & Invoicing
📊 Analytics & Reporting
🤖 All AI Features
⚙️ Settings, Theme, RBAC
Login: admin@property-intelligence.demo / admin123
👤 Tenant Portal
📊 Dashboard (balance, upcoming, alerts)
📄 Lease Details & Documents
💰 Payment Dashboard & History
💳 Make Payment (Stripe)
🔄 Autopay Enrollment
🔧 Maintenance Requests (Create/Track)
💬 Chat with Property Management
👤 Profile Management
Login: /tenant-portal/login — OTP-based auth
🔧 Maintenance Portal (Technician)
📊 Technician Dashboard (today's jobs)
📋 Work Order List (mobile-optimized)
📝 Work Order Detail + Completion
📅 Schedule Management
📸 Photo Capture (before/after)
⏱️ Time Tracking with GPS
📶 Offline Support (IndexedDB)
👤 Technician Profile
Login: /maintenance-portal/login — PIN-based auth
🏪 VendorHub Marketplace
📊 Vendor Dashboard (stats, earnings)
📋 Available Jobs Listing
💼 Job Detail + AI Scope
💰 Submit Bids (line items, hours, schedule)
📋 My Bids (pending/awarded/rejected)
🔧 My Jobs (active work)
🧾 Invoice Upload Post-Completion
👤 Vendor Profile & Verification
Access: /maintenance-portal/vendor-hub/

Authentication Architecture

PortalUser Model

  • user_type — pm, tenant, vendor, owner
  • password_hash — Bcrypt hashed
  • tenant_id / vendor_id / owner_id — FK to entity
  • MFA support — mfa_enabled, mfa_secret
  • Verification — email_verified, phone_verified

Auth Methods

  • PM Portal — Username/password → JWT
  • Tenant Portal — OTP-based (email/SMS)
  • Maintenance Portal — Employee ID + PIN
  • Magic Links — Token-based passwordless auth
  • Token Refresh — Refresh token with device tracking
9

AI-Powered Features

UnitCycle integrates AI throughout the platform — from tenant screening to lease generation, maintenance prediction, and portfolio-wide intelligence. All AI features use the OpenRouter API with Gemini Flash.

AI

🤖 Portfolio Chat

Natural language query engine for portfolio data
  • Ask questions about your portfolio in plain English
  • "What's the occupancy rate for The Residences?"
  • "Show me all tenants paying over $3000/month"
  • Daily digest summaries
  • Session history with context preservation
AI

🔍 Tenant Screening

AI-scored applicant evaluation
  • 0-100 AI score with component breakdown
  • Income, credit, rental history, employment scores
  • Risk factor identification
  • Approve / Conditional / Deny recommendation
  • 20 demo applications seeded
AI

📄 Lease Generation

3-step wizard producing complete legal documents
  • Deal terms → clause configuration → generate
  • 15 clause types with jurisdiction-aware language
  • ReportLab PDF generation
  • Risk score per clause
  • DocuSign simulation for e-signatures
AI

🔎 Lease Abstraction

Extract structured data from lease PDFs
  • Auto-extract all key terms from signed leases
  • Non-standard clause flagging
  • Confirm → Apply workflow
  • Links to source generated lease
AI

📸 Virtual Staging

AI room staging for vacant unit photos
  • Upload empty room photos
  • Select furniture style
  • AI generates furnished versions
  • Direct publish to syndication listings
AI

📊 Revenue Intelligence

AI-driven rent optimization
  • Market comp analysis per unit
  • Current vs market vs recommended rent
  • Confidence scoring on recommendations
  • Strategy selection (match/below/aggressive)
AI

🔄 Renewal Intelligence

Churn prediction and renewal optimization
  • Churn probability scoring
  • Contributing factor analysis
  • Optimal rent recommendation
  • Auto-generated renewal letters
AI

📞 Smart Collections

AI-powered debt recovery
  • Payment probability prediction
  • Best contact time/method AI
  • Tone-matched message generation
  • Escalation ladder automation
AI

🔮 Predictive Maintenance

AI equipment failure prediction
  • Equipment lifecycle tracking
  • Failure prediction with confidence
  • Risk scoring per unit
  • Auto-generated preventive WOs
AI

📄 Invoice Extraction

AI-powered invoice data extraction
  • Auto-extract vendor, amounts, dates from PDFs
  • GL code assignment
  • Duplicate detection
  • Anomaly flagging
AI

💬 Tenant Comms Intelligence

AI message classification and sentiment
  • Message category/urgency classification
  • Emergency detection
  • Auto-response generation
  • Tenant sentiment tracking (churn correlation)
AI

🔧 Vendor Intelligence

AI vendor performance benchmarking
  • 6-score vendor performance rating
  • Repeat visit alerts (same unit, same issue)
  • Warranty check before dispatching
  • AI dispatch recommendations
  • Invoice benchmarking
10

Data Model & Relationships

The UnitCycle database contains 147 tables across 35 Django apps. Most Yardi-synced tables use managed=False — they're read-only from Django's migration perspective. Extension data uses the companion table pattern.

Core Entity Relationships

🏢 Properties
PK id (UUID)
property_code, name
address, city, state
total_units, current_value
latitude, longitude
managed=False
🏗 PropertiesBuilding
PK id (UUID)
FK → Properties
name, building_number
floors, total_units
managed=False
🚪 UnitsUnit
PK id (UUID)
FK → Properties
FK → Building
unit_number, status
bedrooms, bathrooms, sqft
market_rent, current_rent
managed=False
👤 Tenants
PK id (UUID)
first_name, last_name
email, phone
lease_start, lease_end
rent, balance
managed=False
📄 TenantLease
PK id (UUID)
FK → Properties
FK → Tenants
FK → UnitsUnit
lease_number, monthly_rent
start_date, end_date, status
managed=False
🔧 UnitsMaintenance (WO)
PK id (UUID)
FK → UnitsUnit
FK → VendorsVendor
title, description
priority, status
estimated_cost, actual_cost
managed=False
🏪 VendorsVendor
PK id (UUID)
name, vendor_type
email, phone
overall_rating
service_areas (JSON)
managed=False
💰 TenantLedgerEntry
PK id (UUID)
FK → Tenants
FK → TenantLease
trans_type, trans_date
charge_code, charge_amount
is_open, is_posted
managed=False

Database Patterns

Yardi-Synced Tables (managed=False)

  • Tables synced from Yardi property management system
  • Django cannot ALTER these tables (no migrations)
  • DML only (SELECT, INSERT, UPDATE, DELETE)
  • Models defined with managed = False in Meta
  • Examples: properties, units, tenants, vendors, invoices

Companion Table Pattern

  • When you need to extend a Yardi table's data
  • Create a new managed table with FK to Yardi table
  • Example: TenantLeaseLifecycle → OneToOne(TenantLease)
  • Example: WOSource → work_order_id pointing to UnitsMaintenance
  • Never modify the original Yardi table schema

Django Apps by Domain

Domain Apps Model Count Key Tables
Core core, authentication, dashboard 6 portal_users, portal_otp, global_settings
Property properties, units, assets 17 properties, units_unit, assets_asset
Tenants tenants, tenant_portal, tenant_onboarding 20 tenants, tenant_lease, tenant_ledger_entry
Leasing screening, lease_generation, lease_abstraction 4 screening_application, generated_lease
Maintenance maintenance_portal, predictive_maintenance 21 units_maintenance, marketplace_jobs, iot_sensors
Finance invoices, pricing, smart_collections, reserves 18 invoices, collection_case, pricing_snapshot
Lifecycle renewals, turnover 6 renewal_recommendation, turnover_case
Vendors vendors, vendor_intelligence 6 vendors_vendor, vendor_performance
Inspections move_in_inspections, moveout_photos 5 move_in_inspection, moveout_inspection
Marketing staging, syndication, showings 5 staging_project, syndication_listing, showing
Communications communications, tenant_comms, portfolio_chat 5 tenant_message, chat_session
Compliance insurance_compliance, legal_overrides, law_monitor, bk_anomalien 7 insurance_alerts, legal_overrides, bk_anomalien
11

API Reference

All API endpoints are served under https://demo.unitcycle.com/api/v1/. The Django REST API uses ViewSets with automatic router registration.

Domain Endpoint Methods Description
Core/health/GETHealth check
/settings/GET PUTGlobal settings (currency, etc.)
/auth/login/POSTJWT authentication
Properties/properties/GET POSTProperty CRUD
/properties/:id/units/GETUnits for property
/buildings/GET POSTBuilding CRUD
Units/units/GET POSTUnit CRUD with filters
/maintenance/GET POSTWork order CRUD
Tenants/tenants/GET POSTTenant CRUD
/leases/GETLease lifecycle management
/tenants/statistics/GETTenant statistics
Leasing/screening/applications/GET POSTScreening applications
/lease-generation/leases/GET POSTAI lease generation
/lease-abstraction/abstractions/GET POSTAI lease abstraction
Finance/invoices/GET POSTInvoice CRUD + scan + extract
/collections/GET POSTCollection cases
/pricing/snapshots/GETRevenue pricing data
/reserves/ruecklagen/GETReserve fund management
Lifecycle/renewals/GET POSTRenewal recommendations
/turnovers/GET POSTTurnover management
Maintenance/predictive-maintenance/equipment/GETEquipment inventory
/predictive-maintenance/iot-sensors/GETIoT sensor data
/predictive-maintenance/predictions/GETMaintenance predictions
Marketing/staging/projects/GET POSTVirtual staging
/syndication/listings/GET POSTListing syndication
/showings/showings/GET POSTSmart showings
Vendors/vendors/GET POSTVendor directory
/vendor-intelligence/performance/GETVendor performance scores
Portals/tenant-portal/**Various~35 tenant self-service endpoints
/maintenance-portal/**Various~30 technician/vendor endpoints
/auth/**Various~15 authentication endpoints
12

Tech Stack & Infrastructure

Frontend

  • Angular 19 — Standalone components, signals-based reactivity
  • TailwindCSS 3.4 — Utility-first CSS with custom design tokens
  • ApexCharts — All charts and visualizations (never Highcharts)
  • Leaflet — Maps with CARTO Dark Matter tiles
  • ReportLab — PDF generation (lease documents)
  • ng2-pdf-viewer — In-app PDF display

Backend

  • Django 5.x — Python web framework
  • Django REST Framework — API layer with ViewSets
  • PostgreSQL 17 — Primary database (147 tables)
  • JWT — Token-based authentication
  • OpenRouter API — AI features via Gemini Flash
  • WebSockets — Real-time updates

Infrastructure

  • Contabo VPS — Hosting (77.237.235.106)
  • Nginx — Reverse proxy + static files
  • PM2 — Process manager (2 processes)
  • Let's Encrypt — SSL certificates
  • Port 4400 — Angular frontend
  • Port 3001 — Django API

Design System

  • Primary — Navy #0F172A
  • Accent — Gold #EAB308 (all positive indicators)
  • Secondary — Teal #14B8A6
  • Fonts — Plus Jakarta Sans (headings), DM Sans (body)
  • Theme System — 208 CSS variables, 7 presets, runtime switching
  • Light theme preferred — White bg, warm neutrals

Development Workflow

  • Build: rm -rf .angular/cache && npx ng build
  • API Check: python manage.py check
  • Restart: pm2 restart unitcycle-demo
  • Never use ng serve or runserver
  • Live URL: https://demo.unitcycle.com
  • Branch: rafaels-branch-v3

Database Stats

  • 147 tables across 35 Django apps
  • ~24 properties in portfolio
  • ~5,413 units across all properties
  • ~4,617 tenants (1,716 seeded)
  • ~700 vendors in directory
  • 50K+ ledger entries for financial history

Management Commands (39 Seed Scripts)

Every feature area has dedicated seed commands to populate demo data:

seed_work_orders seed_bids seed_pets seed_financials seed_equipment seed_iot_sensors seed_risk_scores seed_collection_cases seed_screening seed_lease_generation seed_lease_abstraction seed_staging seed_syndication seed_showings seed_tenant_onboarding seed_move_in_inspections seed_moveout_photos seed_turnover_cases seed_tenant_comms seed_vendor_intelligence seed_pricing seed_reserves seed_anomalies seed_eigentuemer seed_legal_overrides seed_law_changes seed_chat_sessions seed_lifecycle seed_wo_sources seed_maintenance_schedules seed_delinquency seed_invoice_extractions run_renewal_scan transition_expired_leases backfill_sparse_ledger

UnitCycle — Real Estate Intelligence Platform

Platform Blueprint v1.0 — Generated April 2026

https://demo.unitcycle.com