# ahdimel/real_estate_analysis architecture

> Architecture diagram of the GitHub repository ahdimel/real_estate_analysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahdimel/real_estate_analysis
- Repository: https://github.com/ahdimel/real_estate_analysis

## Overview

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: [`backend/main.py`](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/main.py) (API entry), [`backend/routes/auth.py`](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/routes/auth.py) (Auth), [`backend/routes/properties.py`](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/routes/properties.py) (Properties), [`backend/routes/analysis.py`](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/routes/analysis.py) (Analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js UI"]
  node_ui_shell["App shell<br/>next app<br/>[layout.tsx]"]
  node_ui_dashboard["Dashboard<br/>page<br/>[page.tsx]"]
  node_ui_auth_pages["Auth pages<br/>[page.tsx]"]
  node_ui_property_pages["Property pages<br/>[page.tsx]"]
  node_ui_property_form["Property form<br/>[PropertyForm.tsx]"]
  node_ui_auth_state["Auth state<br/>client context<br/>[AuthContext.tsx]"]
  node_ui_api_client["API client<br/>http client<br/>[api.ts]"]
end

subgraph group_backend["FastAPI API"]
  node_api_entry["API entry<br/>fastapi app<br/>[main.py]"]
  node_api_auth["Auth<br/>route<br/>[auth.py]"]
  node_api_properties["Properties<br/>route<br/>[properties.py]"]
  node_api_analysis["Analysis<br/>route<br/>[analysis.py]"]
  node_api_market["Market<br/>route<br/>[market.py]"]
  node_api_scraper["Scraper<br/>route<br/>[scraper.py]"]
  node_db_models[("Models<br/>orm entities<br/>[property.py]")]
  node_db_core[("Database<br/>persistence<br/>[database.py]")]
  node_analysis_engine{{"Analysis engine<br/>domain logic<br/>[rental.py]"}}
  node_security_layer["Security<br/>auth infra<br/>[security.py]"]
  node_email_service["Email verification<br/>mail flow<br/>[email.py]"]
  node_scraper_engine["Zillow scraper<br/>ingestion<br/>[zillow.py]"]
end

subgraph group_external["External Inputs"]
  node_listing_sites(("Listing sites<br/>external source"))
end

node_ui_shell -->|"renders"| node_ui_dashboard
node_ui_dashboard -->|"loads data"| node_ui_api_client
node_ui_auth_pages -->|"updates"| node_ui_auth_state
node_ui_property_pages -->|"uses"| node_ui_property_form
node_ui_property_pages -->|"submits"| node_ui_api_client
node_ui_api_client -->|"HTTP"| node_api_entry
node_api_entry -->|"routes"| node_api_auth
node_api_entry -->|"routes"| node_api_properties
node_api_entry -->|"routes"| node_api_analysis
node_api_entry -->|"routes"| node_api_market
node_api_entry -->|"routes"| node_api_scraper
node_api_auth -->|"uses"| node_security_layer
node_api_auth -->|"verifies"| node_email_service
node_api_properties -->|"persists"| node_db_models
node_api_properties -->|"uses"| node_db_core
node_api_analysis -->|"computes"| node_analysis_engine
node_api_analysis -->|"reads"| node_db_models
node_api_market -->|"feeds"| node_analysis_engine
node_api_scraper -->|"delegates"| node_scraper_engine
node_scraper_engine -->|"ingests"| node_listing_sites
node_db_models -->|"stored in"| node_db_core

click node_ui_shell "https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/app/layout.tsx"
click node_ui_dashboard "https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/app/dashboard/page.tsx"
click node_ui_auth_pages "https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/app/login/page.tsx"
click node_ui_property_pages "https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/app/properties/new/page.tsx"
click node_ui_property_form "https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/components/PropertyForm.tsx"
click node_ui_auth_state "https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/context/AuthContext.tsx"
click node_ui_api_client "https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/lib/api.ts"
click node_api_entry "https://github.com/ahdimel/real_estate_analysis/blob/main/backend/main.py"
click node_api_auth "https://github.com/ahdimel/real_estate_analysis/blob/main/backend/routes/auth.py"
click node_api_properties "https://github.com/ahdimel/real_estate_analysis/blob/main/backend/routes/properties.py"
click node_api_analysis "https://github.com/ahdimel/real_estate_analysis/blob/main/backend/routes/analysis.py"
click node_api_market "https://github.com/ahdimel/real_estate_analysis/blob/main/backend/routes/market.py"
click node_api_scraper "https://github.com/ahdimel/real_estate_analysis/blob/main/backend/routes/scraper.py"
click node_db_models "https://github.com/ahdimel/real_estate_analysis/blob/main/backend/models/property.py"
click node_db_core "https://github.com/ahdimel/real_estate_analysis/blob/main/backend/database.py"
click node_analysis_engine "https://github.com/ahdimel/real_estate_analysis/blob/main/backend/analysis/rental.py"
click node_security_layer "https://github.com/ahdimel/real_estate_analysis/blob/main/backend/security.py"
click node_email_service "https://github.com/ahdimel/real_estate_analysis/blob/main/backend/email.py"
click node_scraper_engine "https://github.com/ahdimel/real_estate_analysis/blob/main/backend/scraper/zillow.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui_shell,node_ui_dashboard,node_ui_auth_pages,node_ui_property_pages,node_ui_property_form,node_ui_auth_state,node_ui_api_client toneBlue
class node_api_entry,node_api_auth,node_api_properties,node_api_analysis,node_api_market,node_api_scraper,node_db_models,node_db_core,node_analysis_engine,node_security_layer,node_email_service,node_scraper_engine toneAmber
class node_listing_sites toneMint
```

## Components

### Next.js UI

User-facing application and client-side state

- [App shell](https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/app/layout.tsx): next app · Next.js root layout and landing entry · `frontend/app/layout.tsx`
- [Dashboard](https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/app/dashboard/page.tsx): page · Main property overview and workflow hub · `frontend/app/dashboard/page.tsx`
- [Auth pages](https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/app/login/page.tsx): pages · Login and registration screens · `frontend/app/login/page.tsx`
- [Property pages](https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/app/properties/new/page.tsx): pages · Create, edit, and analysis views for properties · `frontend/app/properties/new/page.tsx`
- [Property form](https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/components/PropertyForm.tsx): Reusable create/edit form boundary · `frontend/components/PropertyForm.tsx`
- [Auth state](https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/context/AuthContext.tsx): client context · Shared client-side authentication state · `frontend/context/AuthContext.tsx`
- [API client](https://github.com/ahdimel/real_estate_analysis/blob/main/frontend/lib/api.ts): http client · Frontend HTTP boundary to the backend API · `frontend/lib/api.ts`

### FastAPI API

Server-side domain logic, persistence, and integrations

- [API entry](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/main.py): fastapi app · FastAPI application bootstrap and wiring · `backend/main.py`
- [Auth](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/routes/auth.py): route · Registration, login, and account lifecycle endpoints · `backend/routes/auth.py`
- [Properties](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/routes/properties.py): route · Property CRUD and persistence endpoints · `backend/routes/properties.py`
- [Analysis](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/routes/analysis.py): route · Property investment calculation API · `backend/routes/analysis.py`
- [Market](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/routes/market.py): route · Market-level API surface for comparative inputs · `backend/routes/market.py`
- [Scraper](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/routes/scraper.py): route · Listing URL ingestion endpoint · `backend/routes/scraper.py`
- [Models](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/models/property.py): orm entities · User, property, settings, and email verification entities · `backend/models/property.py`
- [Database](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/database.py): persistence · Database session and engine wiring · `backend/database.py`
- [Analysis engine](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/analysis/rental.py): domain logic · Deterministic rental and market calculations · `backend/analysis/rental.py`
- [Security](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/security.py): auth infra · Password and token/security helpers · `backend/security.py`
- [Email verification](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/email.py): mail flow · Email verification support for account activation · `backend/email.py`
- [Zillow scraper](https://github.com/ahdimel/real_estate_analysis/blob/main/backend/scraper/zillow.py): ingestion · External listing metadata retrieval · `backend/scraper/zillow.py`

### External Inputs

Third-party listing sites and infrastructure

- **Listing sites**: external source · Zillow and Redfin-style property URLs

## Connections

- 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
