How anasb0/prop-rec works
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: routes Route groups · pipeline.py Pipeline · hybrid_recommendation_service.py Hybrid recs · docker-compose.yml Compose stack
Components 22
Frontend
Next.js UI deployed independently and talking to the backend over HTTP.
- Next.js app · App Router pages for landing, login, register, dashboard, properties, and property detail.
app/frontend/src/app - API client · Frontend HTTP client for backend requests.
app/frontend/src/lib/api.ts - Auth helpers · 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 · FastAPI application entrypoint and router wiring.
app/backend/app/main.py - Route groups · Auth, health, properties, interactions, and recommendations endpoints.
app/backend/app/api/routes - Dependencies · Shared request dependencies and auth context setup.
app/backend/app/api/dependencies.py - Security core · JWT validation, token handling, and security primitives.
app/backend/app/core/security.py - Rate limiter · Request throttling and abuse protection.
app/backend/app/core/rate_limiter.py - Auth service · Authentication and user-account business logic.
app/backend/app/services/auth_service.py - Hybrid recs · Recommendation orchestration combining property vectors and user signals.
app/backend/app/services/hybrid_recommendation_service.py - Domain models · User, property, location, features, vectors, recommendations, saved items, interactions, and preferences.
app/backend/app/models - Migrations · Schema evolution for auth, real-estate data, and property vectors.
app/backend/alembic/versions - Relational DB · Transactional store for app state and recommendation metadata.
AI Pipeline
Property text processing, embedding generation, and vector-store ingestion.
- Vector store · Similarity index used for property vector retrieval.
- Ingest job · Standalone property ingestion entrypoint.
app/ai/ingest_properties.py - Pipeline · Coordinates normalization, provider calls, storage, and ingestion flow.
app/ai/pipeline.py - Text processing · Property text normalization and extraction.
app/ai/text_processing.py - Providers · Model-agnostic embedding/provider abstraction.
app/ai/providers.py - LLM client · OpenAI-compatible client for embeddings or generation backends.
app/ai/openai_compatible_client.py - Vector storage · Persistence layer for vectors and searchable records.
app/ai/storage.py
Infra & Docs
Container orchestration and operational documentation.
- Compose stack · Local orchestration for frontend, backend, and vector service.
app/infra/docker-compose.yml - Docs · Operational and architectural documentation.
app/docs/architecture.md
Connections 29
- 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.