# anasb0/prop-rec architecture

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

- Interactive diagram: https://gitdiagram.com/anasb0/prop-rec
- Repository: https://github.com/anasb0/prop-rec

## Overview

1. **Repository shape**
   - This is a monorepo for a property recommendation system with three main codebases:
     - `app/frontend`: Next.js + TypeScript UI
     - `app/backend`: FastAPI service with SQLAlchemy, Alembic, JWT auth
     - `app/ai`: a model-agnostic AI/vectorization helper package
   - `app/infra` contains the container and local orchestration layer, and `app/docs` contains operational/architecture docs.

2. **User-facing frontend**
   - The frontend is a Next.js App Router app with pages for landing, login, registration, dashboard, property list, and property detail.
   - It uses a small API client layer in `src/lib/api.ts` plus auth helpers in `src/lib/auth.ts` to talk to the backend API.
   - The frontend is designed to be deployed independently on Vercel; `NEXT_PUBLIC_API_BASE_URL` points it at the backend.

3. **Backend API boundary**
   - The backend is a FastAPI application exposing route groups for `auth`, `health`, `properties`, `interactions`, and `recommendations`.
   - `app/backend/app/main.py` is the entrypoint; `app/api/dependencies.py` centralizes shared request dependencies.
   - The backend is the system-of-record API for user accounts, property data, recommendation retrieval, and interaction tracking.

4. **Backend domain model**
   - The database schema is split into explicit domain tables/models:
     - `user`
     - `property`
     - `location`
     - `property_feature`
     - `property_vector`
     - `recommendation`
     - `saved_property`
     - `user_interaction`
     - `user_preference`
   - Alembic migrations show the evolution from user auth to a real-estate schema and then vector storage, which suggests the backend owns both transactional state and vector metadata.

5. **Recommendation flow**
   - The core business logic lives in `services/hybrid_recommendation_service.py`.
   - “Hybrid” implies recommendations combine multiple signals, likely property/content similarity from vectors plus user behavior/preferences from relational data.
   - This service is the main orchestration boundary between the transactional database and the vector-backed AI layer.

6. **Authentication and security**
   - Authentication is JWT-based, with configurable issuer/audience/algorithm/secret in `.env`.
   - Security-related code is separated into `core/security.py`, and auth-specific service logic is in `services/auth_service.py`.
   - There is also a rate limiter in `core/rate_limiter.py`, indicating API protection is a first-class backend concern.

7. **AI/vectorization subsystem**
   - `app/ai` is a separate subsystem for ingesting and processing property text into embeddings or searchable representations.
   - Its modules indicate a pipeline:
     - `text_processing.py` for normalization/extraction
     - `providers.py` and `openai_compatible_client.py` for provider abstraction
     - `pipeline.py` to coordinate ingestion
     - `storage.py` for persistence
     - `ingest_properties.py` as the entry script
   - The README’s ChromaDB endpoint and the `property_vectors` model strongly suggest this subsystem feeds a vector store used by recommendations.

8. **Data stores and external services**
   - The architecture includes a relational database for core app state and a vector database/search layer for similarity retrieval.
   - The local stack exposes ChromaDB on port `8001`, the backend on `8000`, and the frontend on `3000`.
   - The AI client is OpenAI-compatible and model-agnostic, so the embedding/provider backend can be swapped without changing the main app architecture.

9. **Infrastructure and runtime**
   - Local development is containerized with `app/infra/docker-compose.yml`.
   - The backend has its own Dockerfile and Alembic migration setup; the frontend also has a Dockerfile.
   - The backend is expected to run on a server/container platform, while the frontend can be deployed separately to Vercel.

10. **Request/data flow at a high level**
   - Browser → Next.js pages/components → frontend API client → FastAPI backend.
   - Backend authenticates requests via JWT, reads/writes relational records, and queries recommendation logic.
   - Recommendation logic consults stored vectors and user behavior/preferences, then returns ranked properties.
   - Separate AI ingestion jobs preprocess property data and populate vector representations used by the recommendation layer.

11. **Operational and quality boundaries**
   - The repo has distinct test layers:
     - backend unit/integration tests and API coverage gates
     - frontend unit tests with Vitest
     - frontend e2e tests with Playwright
     - AI package tests for client/pipeline behavior
   - This separation mirrors the architecture: UI, API, and AI/vectorization are tested as distinct subsystems.

12. **What to draw in an architecture diagram**
   - Show three application layers: frontend, backend API, and AI/vector pipeline.
   - Show the backend connected to a relational database and a vector store.
   - Show the frontend only talking to the backend over HTTP.
   - Show auth as JWT-based and cross-cutting across frontend/backend.
   - Show ingestion as a separate path feeding property vectors into the recommendation system rather than as part of the request/response path.

Main entry points: [`app/backend/app/api/routes`](https://github.com/anasb0/prop-rec/tree/main/app/backend/app/api/routes) (Route groups), [`app/ai/pipeline.py`](https://github.com/anasb0/prop-rec/blob/main/app/ai/pipeline.py) (Pipeline), [`app/backend/app/services/hybrid_recommendation_service.py`](https://github.com/anasb0/prop-rec/blob/main/app/backend/app/services/hybrid_recommendation_service.py) (Hybrid recs), [`app/infra/docker-compose.yml`](https://github.com/anasb0/prop-rec/blob/main/app/infra/docker-compose.yml) (Compose stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Next.js app<br/>ui"]
  node_frontend_api["API client<br/>[api.ts]"]
  node_frontend_auth["Auth helpers<br/>[auth.ts]"]
end

subgraph group_backend["Backend API"]
  node_backend_main["API entry<br/>fastapi<br/>[main.py]"]
  node_backend_routes["Route groups<br/>http routes"]
  node_backend_deps["Dependencies<br/>request context<br/>[dependencies.py]"]
  node_backend_security["Security core<br/>jwt auth<br/>[security.py]"]
  node_backend_rate["Rate limiter<br/>api protection<br/>[rate_limiter.py]"]
  node_backend_authsvc["Auth service<br/>[auth_service.py]"]
  node_backend_recosvc["Hybrid recs"]
  node_backend_models[("Domain models<br/>sqlalchemy models")]
  node_backend_migrations["Migrations<br/>alembic"]
  node_db_relational[("Relational DB<br/>postgres/sqlite")]
end

subgraph group_ai["AI Pipeline"]
  node_vector_store[("Vector store<br/>chromadb")]
  node_ai_ingest["Ingest job<br/>entry script"]
  node_ai_pipeline["Pipeline<br/>[pipeline.py]"]
  node_ai_text["Text processing<br/>preprocess<br/>[text_processing.py]"]
  node_ai_providers["Providers<br/>model abstraction<br/>[providers.py]"]
  node_ai_client["LLM client<br/>openai-compatible"]
  node_ai_storage["Vector storage<br/>persistence<br/>[storage.py]"]
end

subgraph group_infra["Infra & Docs"]
  node_infra_compose["Compose stack<br/>docker compose<br/>[docker-compose.yml]"]
  node_docs_ops["Docs<br/>runbook/architecture<br/>[architecture.md]"]
end

node_frontend_app -->|"calls"| node_frontend_api
node_frontend_app -->|"uses"| node_frontend_auth
node_frontend_api -->|"HTTP"| node_backend_main
node_frontend_auth -->|"JWT login"| node_backend_routes
node_backend_main -->|"mounts"| node_backend_routes
node_backend_routes -->|"depends on"| node_backend_deps
node_backend_routes -->|"enforces"| node_backend_security
node_backend_routes -->|"protected by"| node_backend_rate
node_backend_routes -->|"auth logic"| node_backend_authsvc
node_backend_routes -->|"recommendations"| node_backend_recosvc
node_backend_recosvc -->|"reads/writes"| node_backend_models
node_backend_recosvc -->|"queries"| node_db_relational
node_backend_recosvc -->|"retrieves"| node_vector_store
node_backend_authsvc -->|"accounts"| node_backend_models
node_backend_models -->|"persists to"| node_db_relational
node_backend_migrations -->|"evolves"| node_db_relational
node_ai_ingest -->|"starts"| node_ai_pipeline
node_ai_pipeline -->|"normalizes"| node_ai_text
node_ai_pipeline -->|"embeds via"| node_ai_providers
node_ai_providers -->|"uses"| node_ai_client
node_ai_pipeline -->|"stores"| node_ai_storage
node_ai_storage -->|"writes to"| node_vector_store
node_backend_models -->|"vector metadata"| node_vector_store
node_infra_compose -->|"runs"| node_backend_main
node_infra_compose -->|"runs"| node_frontend_app
node_infra_compose -->|"runs"| node_vector_store
node_docs_ops -.->|"documents"| node_infra_compose
node_docs_ops -.->|"documents"| node_backend_main
node_docs_ops -.->|"documents"| node_ai_pipeline

click node_frontend_app "https://github.com/anasb0/prop-rec/tree/main/app/frontend/src/app"
click node_frontend_api "https://github.com/anasb0/prop-rec/blob/main/app/frontend/src/lib/api.ts"
click node_frontend_auth "https://github.com/anasb0/prop-rec/blob/main/app/frontend/src/lib/auth.ts"
click node_backend_main "https://github.com/anasb0/prop-rec/blob/main/app/backend/app/main.py"
click node_backend_routes "https://github.com/anasb0/prop-rec/tree/main/app/backend/app/api/routes"
click node_backend_deps "https://github.com/anasb0/prop-rec/blob/main/app/backend/app/api/dependencies.py"
click node_backend_security "https://github.com/anasb0/prop-rec/blob/main/app/backend/app/core/security.py"
click node_backend_rate "https://github.com/anasb0/prop-rec/blob/main/app/backend/app/core/rate_limiter.py"
click node_backend_authsvc "https://github.com/anasb0/prop-rec/blob/main/app/backend/app/services/auth_service.py"
click node_backend_recosvc "https://github.com/anasb0/prop-rec/blob/main/app/backend/app/services/hybrid_recommendation_service.py"
click node_backend_models "https://github.com/anasb0/prop-rec/tree/main/app/backend/app/models"
click node_backend_migrations "https://github.com/anasb0/prop-rec/tree/main/app/backend/alembic/versions"
click node_ai_ingest "https://github.com/anasb0/prop-rec/blob/main/app/ai/ingest_properties.py"
click node_ai_pipeline "https://github.com/anasb0/prop-rec/blob/main/app/ai/pipeline.py"
click node_ai_text "https://github.com/anasb0/prop-rec/blob/main/app/ai/text_processing.py"
click node_ai_providers "https://github.com/anasb0/prop-rec/blob/main/app/ai/providers.py"
click node_ai_client "https://github.com/anasb0/prop-rec/blob/main/app/ai/openai_compatible_client.py"
click node_ai_storage "https://github.com/anasb0/prop-rec/blob/main/app/ai/storage.py"
click node_infra_compose "https://github.com/anasb0/prop-rec/blob/main/app/infra/docker-compose.yml"
click node_docs_ops "https://github.com/anasb0/prop-rec/blob/main/app/docs/architecture.md"

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_frontend_app,node_frontend_api,node_frontend_auth toneBlue
class node_backend_main,node_backend_routes,node_backend_deps,node_backend_security,node_backend_rate,node_backend_authsvc,node_backend_recosvc,node_backend_models,node_backend_migrations,node_db_relational toneAmber
class node_vector_store,node_ai_ingest,node_ai_pipeline,node_ai_text,node_ai_providers,node_ai_client,node_ai_storage toneMint
class node_infra_compose,node_docs_ops toneRose
```

## Components

### Frontend

Next.js UI deployed independently and talking to the backend over HTTP.

- [Next.js app](https://github.com/anasb0/prop-rec/tree/main/app/frontend/src/app): ui · App Router pages for landing, login, register, dashboard, properties, and property detail. · `app/frontend/src/app`
- [API client](https://github.com/anasb0/prop-rec/blob/main/app/frontend/src/lib/api.ts): client · Frontend HTTP client for backend requests. · `app/frontend/src/lib/api.ts`
- [Auth helpers](https://github.com/anasb0/prop-rec/blob/main/app/frontend/src/lib/auth.ts): auth · Frontend auth/session helpers used by pages and API calls. · `app/frontend/src/lib/auth.ts`

### Backend API

FastAPI system-of-record for auth, properties, interactions, and recommendations.

- [API entry](https://github.com/anasb0/prop-rec/blob/main/app/backend/app/main.py): fastapi · FastAPI application entrypoint and router wiring. · `app/backend/app/main.py`
- [Route groups](https://github.com/anasb0/prop-rec/tree/main/app/backend/app/api/routes): http routes · Auth, health, properties, interactions, and recommendations endpoints. · `app/backend/app/api/routes`
- [Dependencies](https://github.com/anasb0/prop-rec/blob/main/app/backend/app/api/dependencies.py): request context · Shared request dependencies and auth context setup. · `app/backend/app/api/dependencies.py`
- [Security core](https://github.com/anasb0/prop-rec/blob/main/app/backend/app/core/security.py): jwt auth · JWT validation, token handling, and security primitives. · `app/backend/app/core/security.py`
- [Rate limiter](https://github.com/anasb0/prop-rec/blob/main/app/backend/app/core/rate_limiter.py): api protection · Request throttling and abuse protection. · `app/backend/app/core/rate_limiter.py`
- [Auth service](https://github.com/anasb0/prop-rec/blob/main/app/backend/app/services/auth_service.py): service · Authentication and user-account business logic. · `app/backend/app/services/auth_service.py`
- [Hybrid recs](https://github.com/anasb0/prop-rec/blob/main/app/backend/app/services/hybrid_recommendation_service.py): service · Recommendation orchestration combining property vectors and user signals. · `app/backend/app/services/hybrid_recommendation_service.py`
- [Domain models](https://github.com/anasb0/prop-rec/tree/main/app/backend/app/models): sqlalchemy models · User, property, location, features, vectors, recommendations, saved items, interactions, and preferences. · `app/backend/app/models`
- [Migrations](https://github.com/anasb0/prop-rec/tree/main/app/backend/alembic/versions): alembic · Schema evolution for auth, real-estate data, and property vectors. · `app/backend/alembic/versions`
- **Relational DB**: postgres/sqlite · Transactional store for app state and recommendation metadata.

### AI Pipeline

Property text processing, embedding generation, and vector-store ingestion.

- **Vector store**: chromadb · Similarity index used for property vector retrieval.
- [Ingest job](https://github.com/anasb0/prop-rec/blob/main/app/ai/ingest_properties.py): entry script · Standalone property ingestion entrypoint. · `app/ai/ingest_properties.py`
- [Pipeline](https://github.com/anasb0/prop-rec/blob/main/app/ai/pipeline.py): embeddings pipeline · Coordinates normalization, provider calls, storage, and ingestion flow. · `app/ai/pipeline.py`
- [Text processing](https://github.com/anasb0/prop-rec/blob/main/app/ai/text_processing.py): preprocess · Property text normalization and extraction. · `app/ai/text_processing.py`
- [Providers](https://github.com/anasb0/prop-rec/blob/main/app/ai/providers.py): model abstraction · Model-agnostic embedding/provider abstraction. · `app/ai/providers.py`
- [LLM client](https://github.com/anasb0/prop-rec/blob/main/app/ai/openai_compatible_client.py): openai-compatible · OpenAI-compatible client for embeddings or generation backends. · `app/ai/openai_compatible_client.py`
- [Vector storage](https://github.com/anasb0/prop-rec/blob/main/app/ai/storage.py): persistence · Persistence layer for vectors and searchable records. · `app/ai/storage.py`

### Infra & Docs

Container orchestration and operational documentation.

- [Compose stack](https://github.com/anasb0/prop-rec/blob/main/app/infra/docker-compose.yml): docker compose · Local orchestration for frontend, backend, and vector service. · `app/infra/docker-compose.yml`
- [Docs](https://github.com/anasb0/prop-rec/blob/main/app/docs/architecture.md): runbook/architecture · Operational and architectural documentation. · `app/docs/architecture.md`

## Connections

- Next.js app → API client: calls · Pages use the shared API client for backend requests.
- Next.js app → Auth helpers: uses · Pages and UI flows use auth helpers for session handling.
- API client → API entry: HTTP · Frontend talks to the FastAPI backend over HTTP.
- Auth helpers → Route groups: JWT login · Auth helpers support login/register flows against backend auth routes.
- API entry → Route groups: mounts · Entrypoint wires route groups into the app.
- Route groups → Dependencies: depends on · Routes share request-scoped dependencies and auth context.
- Route groups → Security core: enforces · API routes rely on JWT security primitives.
- Route groups → Rate limiter: protected by · Routes are guarded by rate limiting.
- Route groups → Auth service: auth logic · Auth endpoints delegate to the authentication service.
- Route groups → Hybrid recs: recommendations · Recommendation endpoints delegate to hybrid recommendation logic.
- Hybrid recs → Domain models: reads/writes · Recommendation logic uses domain models and persisted state.
- Hybrid recs → Relational DB: queries · Hybrid recommendations consume relational user and property data.
- Hybrid recs → Vector store: retrieves · Hybrid recommendations consult the vector index for similarity signals.
- Auth service → Domain models: accounts · Auth service manages user records and related security state.
- Domain models → Relational DB: persists to · ORM models map to the transactional database.
- Migrations → Relational DB: evolves · Alembic migrations create and extend the relational schema.
- Ingest job → Pipeline: starts · The ingestion script launches the pipeline.
- Pipeline → Text processing: normalizes · Pipeline preprocesses property text before embedding.
- Pipeline → Providers: embeds via · Pipeline uses provider abstraction for model access.
- Providers → LLM client: uses · Provider layer is backed by an OpenAI-compatible client.
- Pipeline → Vector storage: stores · Pipeline persists vector outputs and searchable records.
- Vector storage → Vector store: writes to · AI storage feeds the vector database/search layer.
- Domain models → Vector store: vector metadata · Property vector domain records mirror the searchable vector layer.
- Compose stack → API entry: runs · Compose brings up the backend service locally.
- Compose stack → Next.js app: runs · Compose brings up the frontend service locally.
- Compose stack → Vector store: runs · Compose exposes the local vector database.
- Docs → Compose stack: documents · Docs describe the local stack and runtime boundaries.
- Docs → API entry: documents · Docs capture backend architecture and operations.
- Docs → Pipeline: documents · Docs capture AI/vectorization workflow.
