How ahdimel/real_estate_analysis works
1. What this system is
- REI is a two-part application: a FastAPI backend that owns authentication, persistence, scraping, and analysis, and a Next.js frontend that provides the user-facing investment workflow.
- The core domain is rental property analysis: users add properties, enrich them from listing URLs, and run deterministic investment calculations.
2. Primary runtime boundary
- The backend runs as a Python API server on port 8000.
- The frontend runs as a separate Node/Next.js app on port 3000.
- The frontend talks to the backend over HTTP through a small API client layer in frontend/lib/api.ts.
3. Backend application structure
- backend/main.py is the FastAPI entry point.
- The backend is organized into clear layers:
- routes/ for HTTP endpoints
- analysis/ for domain calculation logic
- models/ for database entities
- schemas/ for request/response shapes
- scraper/ for external property metadata retrieval
- security.py, dependencies.py, email.py, and database.py for cross-cutting infrastructure
4. Persistence layer
- The data model is centered on SQLAlchemy-style entities in backend/models/.
- backend/database.py wires database access; the README indicates SQLite for development and PostgreSQL for production.
- The visible models suggest these core tables/entities:
- user
- property
- settings
- email_verification
- This implies a multi-user system where properties and analysis state are stored server-side.
5. Authentication and account lifecycle
- Authentication is handled in backend/routes/auth.py, with supporting logic in security.py.
- backend/models/email_verification.py and backend/email.py indicate an email verification flow after registration.
- Frontend pages for /login and /register, plus frontend/context/AuthContext.tsx, show that auth state is managed client-side and shared across the UI.
6. Property management workflow
- Properties are a first-class domain object, with route handlers in backend/routes/properties.py and matching schemas/models.
- The frontend provides pages for:
- listing/dashboard views
- creating a property
- editing a property
- viewing property-specific analysis
- frontend/components/PropertyForm.tsx is the reusable UI boundary for create/edit operations.
7. Scraping and external data ingestion
- backend/routes/scraper.py and backend/scraper/zillow.py are the ingestion boundary for pulling metadata from listing URLs.
- The README says Zillow/Redfin URLs are supported; the code tree shows at least a dedicated Zillow scraper module.
- This is an external-data subsystem: user-supplied listing URLs are transformed into structured property attributes before analysis.
8. Analysis engine
- The domain logic for investment calculations lives in backend/analysis/, with separate modules for rental.py and market.py.
- backend/routes/analysis.py exposes these calculations over the API.
- The “deterministic” aspect means the backend computes results from stored inputs rather than relying on opaque ML inference or third-party scoring.
9. Market data boundary
- backend/routes/market.py suggests a separate API surface for market-related inputs or summaries.
- In architecture terms, this is distinct from per-property analysis: market-level data likely feeds assumptions or comparative context rather than being tied to one property record.
10. Frontend application structure
- The frontend uses the Next.js App Router with route-based pages:
- /dashboard
- /login
- /register
- /properties/new
- /properties/[id]/edit
- /properties/[id]/analysis
- frontend/app/layout.tsx and globals.css define the app shell and global styling.
- The frontend is thin relative to the backend: it renders forms, navigation, and results, while the backend owns business rules and persistence.
11. Shared contracts between frontend and backend
- backend/schemas/ define the API contract shape for users, properties, and analysis.
- These schemas are the explicit boundary between stored domain objects and HTTP payloads.
- This separation is important for diagramming: UI components consume API responses, while backend routes validate and serialize through schemas.
12. Testing and quality boundary
- Backend tests live in backend/tests/ and cover:
- auth
- properties
- analysis
- conftest.py indicates shared test fixtures, likely for database/app setup.
- The test footprint suggests the backend is the primary correctness boundary; frontend testing is not visible in the tree.
13. How the main data flow works
- A user registers/logs in through the frontend.
- The frontend stores auth state and calls backend APIs.
- The user creates or edits a property.
- If they provide a Zillow/Redfin URL, the backend scraper enriches the property data.
- The backend persists the property and runs rental/market analysis.
- Results are returned to the frontend for display on dashboard and property analysis pages.
14. What to emphasize in an architecture diagram
- Show two major deployable units: Next.js UI and FastAPI API.
- Show backend subdomains as separate boxes: Auth, Property CRUD, Scraping, Analysis, Market, Persistence, Email Verification.
- Show the database as a single shared store beneath the backend.
- Show external listing sites as an inbound integration into the scraper, not as a direct frontend dependency.
Main entry points: main.py API entry · auth.py Auth · properties.py Properties · analysis.py Analysis
Components 20
Next.js UI
User-facing application and client-side state
- App shell · Next.js root layout and landing entry
frontend/app/layout.tsx - Dashboard · Main property overview and workflow hub
frontend/app/dashboard/page.tsx - Auth pages · Login and registration screens
frontend/app/login/page.tsx - Property pages · Create, edit, and analysis views for properties
frontend/app/properties/new/page.tsx - Property form · Reusable create/edit form boundary
frontend/components/PropertyForm.tsx - Auth state · Shared client-side authentication state
frontend/context/AuthContext.tsx - API client · Frontend HTTP boundary to the backend API
frontend/lib/api.ts
FastAPI API
Server-side domain logic, persistence, and integrations
- API entry · FastAPI application bootstrap and wiring
backend/main.py - Auth · Registration, login, and account lifecycle endpoints
backend/routes/auth.py - Properties · Property CRUD and persistence endpoints
backend/routes/properties.py - Analysis · Property investment calculation API
backend/routes/analysis.py - Market · Market-level API surface for comparative inputs
backend/routes/market.py - Scraper · Listing URL ingestion endpoint
backend/routes/scraper.py - Models · User, property, settings, and email verification entities
backend/models/property.py - Database · Database session and engine wiring
backend/database.py - Analysis engine · Deterministic rental and market calculations
backend/analysis/rental.py - Security · Password and token/security helpers
backend/security.py - Email verification · Email verification support for account activation
backend/email.py - Zillow scraper · External listing metadata retrieval
backend/scraper/zillow.py
External Inputs
Third-party listing sites and infrastructure
- Listing sites · Zillow and Redfin-style property URLs
Connections 21
- App shell → Dashboard: renders · App shell hosts the main UI routes
- Dashboard → API client: loads data · Dashboard fetches properties and analysis results
- Auth pages → Auth state: updates · Login and register flow updates shared auth state
- Property pages → Property form: uses · Create and edit pages reuse the property form
- Property pages → API client: submits · Property workflows call backend APIs through the client
- API client → API entry: HTTP · Frontend talks to the FastAPI backend over HTTP
- API entry → Auth: routes · Main app wires auth endpoints
- API entry → Properties: routes · Main app wires property endpoints
- API entry → Analysis: routes · Main app wires analysis endpoints
- API entry → Market: routes · Main app wires market endpoints
- API entry → Scraper: routes · Main app wires scraping endpoints
- Auth → Security: uses · Auth endpoints rely on security helpers
- Auth → Email verification: verifies · Registration flow triggers email verification
- Properties → Models: persists · Property CRUD reads and writes ORM entities
- Properties → Database: uses · Property routes use shared database access
- Analysis → Analysis engine: computes · Analysis routes expose deterministic calculations
- Analysis → Models: reads · Analysis uses stored property and settings data
- Market → Analysis engine: feeds · Market endpoints provide inputs to analysis logic
- Scraper → Zillow scraper: delegates · Scraper routes delegate URL ingestion to scraper code
- Zillow scraper → Listing sites: ingests · External listing URLs are transformed into structured property data
- Models → Database: stored in · ORM entities are persisted through the database layer