# urbanscope-ph/miriam-lobren-realestate architecture

> Architecture diagram of the GitHub repository urbanscope-ph/miriam-lobren-realestate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/urbanscope-ph/miriam-lobren-realestate
- Repository: https://github.com/urbanscope-ph/miriam-lobren-realestate

## Overview

UrbanScope is a real-estate discovery and client-inquiry site with separate agent-admin and superadmin portals. Homebuyers browse listings, register or sign in, submit consultation or property inquiries, then manage inquiry history; staff manage listings and inquiries, while superadmins govern accounts and inspect system health. The backend provides API routing, authentication and authorization, and SQLite persistence. README capabilities are retained, but some frontend-to-API wiring and unsampled implementations are shown only where documented; relationships without evidence are omitted.

Main entry points: [`backend/app.py`](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/app.py) (FastAPI Application), [`backend/database.py`](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/database.py) (SQLite Database), [`backend/auth.py`](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/auth.py) (Auth and RBAC), [`backend/routers/auth.py`](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/routers/auth.py) (Authentication API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Homebuyer Experience"]
  node_catalog["Property Catalog<br/>[index.js]"]
  node_property_detail["Property Details<br/>[property-detail.js]"]
  node_client_auth["Client Sign-in"]
  node_consultation["Consultation Inquiry<br/>[inquiry.js]"]
  node_inquiry_history["Inquiry History<br/>[history.js]"]
  node_legal["Legal and Privacy<br/>[legal.js]"]
end

subgraph group_admin["Agent Administration"]
  node_admin_portal["Admin Dashboard<br/>[dashboard.js]"]
  node_admin_properties["Property Management<br/>[properties.js]"]
  node_admin_clients["Client Management<br/>[clients.js]"]
  node_admin_shell["Admin Navigation<br/>[admin-shell.js]"]
end

subgraph group_governance["Superadmin Governance"]
  node_superadmin_ui["Superadmin Console<br/>[dashboard.js]"]
  node_superadmin_api["Account Governance API<br/>[superadmin.py]"]
end

subgraph group_backend["FastAPI Services"]
  node_web_hosting["Web Hosting Routes<br/>[web.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_property_api["Property API<br/>[properties.py]"]
  node_inquiry_api["Inquiry Lifecycle API<br/>[inquiries.py]"]
  node_system_api["System API<br/>[system.py]"]
  node_app["FastAPI Application<br/>[app.py]"]
  node_database[("SQLite Database<br/>[database.py]")]
  node_models["Request Models<br/>[models.py]"]
  node_middleware["Admin Guard<br/>[middleware.py]"]
end

subgraph group_identity["Identity and Sessions"]
  node_auth_core["Auth and RBAC<br/>[auth.py]"]
  node_otp_core["Email OTP Service<br/>[auth_otp.py]"]
  node_edge_session["Admin Session Endpoint<br/>[edge-session.js]"]
  node_session_lib["Signed Session Library<br/>[admin-session.js]"]
  node_email_auth["Email Auth Utilities<br/>[email-auth.js]"]
  node_register_start["Registration Code Endpoint<br/>[start.js]"]
  node_register_verify["Registration Verify Endpoint<br/>[verify.js]"]
  node_superadmin_users["Cloud Account Endpoint<br/>[users.js]"]
end

node_buyer(("Homebuyer"))
node_smtp["Email Delivery"]
node_supabase[("Supabase Auth Data")]

node_buyer -->|"browses"| node_catalog
node_catalog -->|"opens listing"| node_property_detail
node_buyer -->|"registers or signs in"| node_client_auth
node_buyer -->|"submits inquiry"| node_consultation
node_buyer -->|"manages requests"| node_inquiry_history
node_buyer -->|"reviews policies"| node_legal
node_admin_portal -->|"manages listings"| node_admin_properties
node_admin_portal -->|"tracks clients"| node_admin_clients
node_admin_shell -->|"provides navigation"| node_admin_portal
node_superadmin_ui -->|"governs accounts"| node_superadmin_api
node_app -->|"registers hosting"| node_web_hosting
node_app -->|"registers router"| node_auth_api
node_app -->|"registers router"| node_property_api
node_app -->|"registers router"| node_inquiry_api
node_app -->|"registers router"| node_superadmin_api
node_app -->|"registers router"| node_system_api
node_app -->|"installs guard"| node_middleware
node_app -->|"initializes"| node_database
node_auth_api -->|"uses identity"| node_auth_core
node_auth_api -->|"uses OTP"| node_otp_core
node_auth_api -->|"reads and writes"| node_database
node_auth_api -->|"validates payloads"| node_models
node_property_api -->|"reads and writes"| node_database
node_property_api -->|"checks access"| node_auth_core
node_property_api -->|"uses schemas"| node_models
node_inquiry_api -->|"reads and writes"| node_database
node_inquiry_api -->|"checks access"| node_auth_core
node_inquiry_api -->|"uses schemas"| node_models
node_superadmin_api -->|"reads and writes"| node_database
node_superadmin_api -->|"checks role"| node_auth_core
node_system_api -->|"checks system state"| node_database
node_system_api -->|"checks access"| node_auth_core
node_middleware -->|"checks authorization"| node_auth_core
node_middleware -->|"loads user"| node_database
node_auth_core -->|"loads account"| node_database
node_edge_session -->|"creates and reads"| node_session_lib
node_register_start -->|"issues code"| node_email_auth
node_register_verify -->|"verifies code"| node_email_auth
node_superadmin_users -->|"manages accounts"| node_email_auth
node_superadmin_users -->|"checks session"| node_session_lib
node_email_auth -->|"sends code"| node_smtp
node_email_auth -->|"stores challenges"| node_supabase
node_edge_session -->|"verifies staff"| node_supabase

click node_catalog "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/index.js"
click node_property_detail "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/properties/property-detail.js"
click node_client_auth "https://github.com/urbanscope-ph/miriam-lobren-realestate/tree/main/frontend/pages/auth"
click node_consultation "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/inquiry/inquiry.js"
click node_inquiry_history "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/inquiry/history.js"
click node_legal "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/legal/legal.js"
click node_admin_portal "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/admin/dashboard.js"
click node_admin_properties "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/admin/properties.js"
click node_admin_clients "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/admin/clients.js"
click node_admin_shell "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/admin/admin-shell.js"
click node_superadmin_ui "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/superadmin/dashboard.js"
click node_superadmin_api "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/routers/superadmin.py"
click node_web_hosting "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/routers/web.py"
click node_auth_api "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/routers/auth.py"
click node_property_api "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/routers/properties.py"
click node_inquiry_api "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/routers/inquiries.py"
click node_system_api "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/routers/system.py"
click node_app "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/app.py"
click node_database "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/database.py"
click node_models "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/models.py"
click node_middleware "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/middleware.py"
click node_auth_core "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/auth.py"
click node_otp_core "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/auth_otp.py"
click node_edge_session "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/api/auth/edge-session.js"
click node_session_lib "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/lib/admin-session.js"
click node_email_auth "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/lib/email-auth.js"
click node_register_start "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/api/auth/register/start.js"
click node_register_verify "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/api/auth/register/verify.js"
click node_superadmin_users "https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/api/superadmin/users.js"

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_catalog,node_property_detail,node_client_auth,node_consultation,node_inquiry_history,node_legal toneBlue
class node_admin_portal,node_admin_properties,node_admin_clients,node_admin_shell,node_supabase toneAmber
class node_superadmin_ui,node_superadmin_api toneMint
class node_web_hosting,node_auth_api,node_property_api,node_inquiry_api,node_system_api,node_app,node_database,node_models,node_middleware toneRose
class node_auth_core,node_otp_core,node_edge_session,node_session_lib,node_email_auth,node_register_start,node_register_verify,node_superadmin_users,node_buyer,node_smtp toneIndigo
```

## Components

### Homebuyer Experience

- [Property Catalog](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/index.js): `frontend/index.js`
- [Property Details](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/properties/property-detail.js): `frontend/pages/properties/property-detail.js`
- [Client Sign-in](https://github.com/urbanscope-ph/miriam-lobren-realestate/tree/main/frontend/pages/auth): `frontend/pages/auth`
- [Consultation Inquiry](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/inquiry/inquiry.js): `frontend/pages/inquiry/inquiry.js`
- [Inquiry History](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/inquiry/history.js): `frontend/pages/inquiry/history.js`
- [Legal and Privacy](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/legal/legal.js): `frontend/pages/legal/legal.js`

### Agent Administration

- [Admin Dashboard](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/admin/dashboard.js): `frontend/pages/admin/dashboard.js`
- [Property Management](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/admin/properties.js): `frontend/pages/admin/properties.js`
- [Client Management](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/admin/clients.js): `frontend/pages/admin/clients.js`
- [Admin Navigation](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/admin/admin-shell.js): `frontend/pages/admin/admin-shell.js`

### Superadmin Governance

- [Superadmin Console](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/frontend/pages/superadmin/dashboard.js): `frontend/pages/superadmin/dashboard.js`
- [Account Governance API](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/routers/superadmin.py): `backend/routers/superadmin.py`

### FastAPI Services

- [Web Hosting Routes](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/routers/web.py): `backend/routers/web.py`
- [Authentication API](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/routers/auth.py): `backend/routers/auth.py`
- [Property API](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/routers/properties.py): `backend/routers/properties.py`
- [Inquiry Lifecycle API](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/routers/inquiries.py): `backend/routers/inquiries.py`
- [System API](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/routers/system.py): `backend/routers/system.py`
- [FastAPI Application](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/app.py): `backend/app.py`
- [SQLite Database](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/database.py): `backend/database.py`
- [Request Models](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/models.py): `backend/models.py`
- [Admin Guard](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/middleware.py): `backend/middleware.py`

### Identity and Sessions

- [Auth and RBAC](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/auth.py): `backend/auth.py`
- [Email OTP Service](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/backend/auth_otp.py): `backend/auth_otp.py`
- [Admin Session Endpoint](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/api/auth/edge-session.js): `api/auth/edge-session.js`
- [Signed Session Library](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/lib/admin-session.js): `lib/admin-session.js`
- [Email Auth Utilities](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/lib/email-auth.js): `lib/email-auth.js`
- [Registration Code Endpoint](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/api/auth/register/start.js): `api/auth/register/start.js`
- [Registration Verify Endpoint](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/api/auth/register/verify.js): `api/auth/register/verify.js`
- [Cloud Account Endpoint](https://github.com/urbanscope-ph/miriam-lobren-realestate/blob/main/api/superadmin/users.js): `api/superadmin/users.js`

### Other components

- **Homebuyer**
- **Email Delivery**
- **Supabase Auth Data**

## Connections

- Homebuyer → Property Catalog: browses
- Property Catalog → Property Details: opens listing
- Homebuyer → Client Sign-in: registers or signs in
- Homebuyer → Consultation Inquiry: submits inquiry
- Homebuyer → Inquiry History: manages requests
- Homebuyer → Legal and Privacy: reviews policies
- Admin Dashboard → Property Management: manages listings
- Admin Dashboard → Client Management: tracks clients
- Admin Navigation → Admin Dashboard: provides navigation
- Superadmin Console → Account Governance API: governs accounts
- FastAPI Application → Web Hosting Routes: registers hosting (evidence: `backend/app.py`)
- FastAPI Application → Authentication API: registers router (evidence: `backend/app.py`)
- FastAPI Application → Property API: registers router (evidence: `backend/app.py`)
- FastAPI Application → Inquiry Lifecycle API: registers router (evidence: `backend/app.py`)
- FastAPI Application → Account Governance API: registers router (evidence: `backend/app.py`)
- FastAPI Application → System API: registers router (evidence: `backend/app.py`)
- FastAPI Application → Admin Guard: installs guard (evidence: `backend/app.py`)
- FastAPI Application → SQLite Database: initializes (evidence: `backend/app.py`)
- Authentication API → Auth and RBAC: uses identity (evidence: `backend/routers/auth.py`)
- Authentication API → Email OTP Service: uses OTP (evidence: `backend/routers/auth.py`)
- Authentication API → SQLite Database: reads and writes (evidence: `backend/routers/auth.py`)
- Authentication API → Request Models: validates payloads (evidence: `backend/routers/auth.py`)
- Property API → SQLite Database: reads and writes (evidence: `backend/routers/properties.py`)
- Property API → Auth and RBAC: checks access (evidence: `backend/routers/properties.py`)
- Property API → Request Models: uses schemas (evidence: `backend/routers/properties.py`)
- Inquiry Lifecycle API → SQLite Database: reads and writes (evidence: `backend/routers/inquiries.py`)
- Inquiry Lifecycle API → Auth and RBAC: checks access (evidence: `backend/routers/inquiries.py`)
- Inquiry Lifecycle API → Request Models: uses schemas (evidence: `backend/routers/inquiries.py`)
- Account Governance API → SQLite Database: reads and writes (evidence: `backend/routers/superadmin.py`)
- Account Governance API → Auth and RBAC: checks role (evidence: `backend/routers/superadmin.py`)
- System API → SQLite Database: checks system state (evidence: `backend/routers/system.py`)
- System API → Auth and RBAC: checks access (evidence: `backend/routers/system.py`)
- Admin Guard → Auth and RBAC: checks authorization (evidence: `backend/middleware.py`)
- Admin Guard → SQLite Database: loads user (evidence: `backend/middleware.py`)
- Auth and RBAC → SQLite Database: loads account (evidence: `backend/auth.py`)
- Admin Session Endpoint → Signed Session Library: creates and reads (evidence: `api/auth/edge-session.js`)
- Registration Code Endpoint → Email Auth Utilities: issues code (evidence: `api/auth/register/start.js`)
- Registration Verify Endpoint → Email Auth Utilities: verifies code (evidence: `api/auth/register/verify.js`)
- Cloud Account Endpoint → Email Auth Utilities: manages accounts (evidence: `api/superadmin/users.js`)
- Cloud Account Endpoint → Signed Session Library: checks session (evidence: `api/superadmin/users.js`)
- Email Auth Utilities → Email Delivery: sends code (evidence: `lib/email-auth.js`)
- Email Auth Utilities → Supabase Auth Data: stores challenges (evidence: `lib/email-auth.js`)
- Admin Session Endpoint → Supabase Auth Data: verifies staff (evidence: `api/auth/edge-session.js`)