# phucbeo223/local-project-for-student-room architecture

> Architecture diagram of the GitHub repository phucbeo223/local-project-for-student-room, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phucbeo223/local-project-for-student-room
- Repository: https://github.com/phucbeo223/local-project-for-student-room

## Overview

TimTroSV is a student-housing discovery and room-service system for students in Cần Thơ. The main user-facing capability is finding and evaluating listings; supporting branches cover account access, saved preferences and recommendations, legal Q&A, listing-risk assessment, and administration. The API entry point also owns crawler startup and manual runs, followed by cleaning. Several subsystems are represented from the SOURCE INDEX and README rather than inspected implementations, so their internal links are omitted where caller evidence is unavailable.

Main entry points: [`apps/api/app/main.py`](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/main.py) (API entry), [`apps/api/app/room_service/risk/service.py`](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/risk/service.py) (Risk assessment), [`apps/api/app/engagement/router.py`](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/engagement/router.py) (Engagement), [`apps/api/app/listings/router.py`](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/listings/router.py) (Listing search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Student experience"]
  node_webapp["Web application<br/>[page.tsx]"]
end

subgraph group_api["API and accounts"]
  node_api_entry["API entry<br/>[main.py]"]
  node_auth["Authentication<br/>[router.py]"]
  node_auth_lifecycle["Account lifecycle<br/>[lifecycle.py]"]
  node_engagement["Engagement<br/>[router.py]"]
  node_engagement_service["Engagement service<br/>[service.py]"]
  node_recommender["Recommendations<br/>[recommender.py]"]
end

subgraph group_housing["Housing data"]
  node_listings["Listing search<br/>[router.py]"]
  node_listing_store[("Listing repository<br/>[repo.py]")]
  node_crawler["Listing crawler<br/>[pipeline.py]"]
  node_cleaner["Listing cleaner<br/>[pipeline.py]"]
end

subgraph group_services["Room services"]
  node_chat_router["Chat API<br/>[router.py]"]
  node_chat_service["Chat orchestration<br/>[service.py]"]
  node_chat_agents["Answer agents<br/>[agents.py]"]
  node_chat_providers["AI providers<br/>[providers.py]"]
  node_risk_service["Risk assessment<br/>[service.py]"]
  node_risk_scoring["Risk scoring<br/>[scoring.py]"]
  node_risk_store[("Risk repository<br/>[repo.py]")]
  node_reports["Reports service<br/>[service.py]"]
end

subgraph group_knowledge["Legal knowledge"]
  node_legal_retrieval["Legal retrieval<br/>[legal_retrieval.py]"]
  node_legal_ingestion["Legal ingestion<br/>[ingestion.py]"]
end

node_student(("Student"))
node_external_ai{{"AI providers"}}

node_student -->|"uses"| node_webapp
node_api_entry -->|"registers routes"| node_listings
node_api_entry -->|"registers routes"| node_chat_router
node_api_entry -->|"registers routes"| node_engagement
node_api_entry -->|"registers routes"| node_auth
node_api_entry -->|"runs source"| node_crawler
node_api_entry -->|"runs cleaning"| node_cleaner
node_crawler -.->|"persists listings"| node_listing_store
node_crawler -.->|"normalizes input"| node_cleaner
node_cleaner -.->|"cleans records"| node_listing_store
node_listings -->|"queries listings"| node_listing_store
node_listings -->|"assesses risk"| node_risk_service
node_auth -->|"manages accounts"| node_auth_lifecycle
node_engagement -->|"calls"| node_engagement_service
node_engagement -->|"ranks candidates"| node_recommender
node_chat_router -->|"dispatches requests"| node_chat_service
node_chat_router -->|"dispatches agents"| node_chat_agents
node_chat_service -->|"generates answers"| node_chat_providers
node_chat_service -->|"retrieves law"| node_legal_retrieval
node_chat_providers -.->|"calls provider"| node_external_ai
node_legal_ingestion -.->|"supplies corpus"| node_legal_retrieval
node_risk_service -->|"scores listings"| node_risk_scoring
node_risk_service -->|"loads and saves"| node_risk_store
node_reports -->|"assesses reports"| node_risk_service

click node_webapp "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/web/src/app/page.tsx"
click node_api_entry "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/main.py"
click node_auth "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/auth/router.py"
click node_auth_lifecycle "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/auth/lifecycle.py"
click node_listings "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/listings/router.py"
click node_listing_store "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/listings/repo.py"
click node_crawler "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/crawler/pipeline.py"
click node_cleaner "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/cleaner/pipeline.py"
click node_engagement "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/engagement/router.py"
click node_engagement_service "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/engagement/service.py"
click node_recommender "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/engagement/recommender.py"
click node_chat_router "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/chatbot/router.py"
click node_chat_service "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/chatbot/service.py"
click node_chat_agents "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/chatbot/agents.py"
click node_chat_providers "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/chatbot/providers.py"
click node_legal_retrieval "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/chatbot/legal_retrieval.py"
click node_legal_ingestion "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/legal_knowledge/ingestion.py"
click node_risk_service "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/risk/service.py"
click node_risk_scoring "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/risk/scoring.py"
click node_risk_store "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/risk/repo.py"
click node_reports "https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/reports/service.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_webapp toneBlue
class node_api_entry,node_auth,node_auth_lifecycle,node_engagement,node_engagement_service,node_recommender toneAmber
class node_listings,node_listing_store,node_crawler,node_cleaner toneMint
class node_chat_router,node_chat_service,node_chat_agents,node_chat_providers,node_risk_service,node_risk_scoring,node_risk_store,node_reports toneRose
class node_legal_retrieval,node_legal_ingestion,node_student,node_external_ai toneIndigo
```

## Components

### Student experience

- [Web application](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/web/src/app/page.tsx): `apps/web/src/app/page.tsx`

### API and accounts

- [API entry](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/main.py): `apps/api/app/main.py`
- [Authentication](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/auth/router.py): `apps/api/app/auth/router.py`
- [Account lifecycle](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/auth/lifecycle.py): `apps/api/app/auth/lifecycle.py`
- [Engagement](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/engagement/router.py): `apps/api/app/engagement/router.py`
- [Engagement service](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/engagement/service.py): `apps/api/app/engagement/service.py`
- [Recommendations](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/engagement/recommender.py): `apps/api/app/engagement/recommender.py`

### Housing data

- [Listing search](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/listings/router.py): `apps/api/app/listings/router.py`
- [Listing repository](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/listings/repo.py): `apps/api/app/listings/repo.py`
- [Listing crawler](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/crawler/pipeline.py): `apps/api/app/crawler/pipeline.py`
- [Listing cleaner](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/cleaner/pipeline.py): `apps/api/app/cleaner/pipeline.py`

### Room services

- [Chat API](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/chatbot/router.py): `apps/api/app/room_service/chatbot/router.py`
- [Chat orchestration](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/chatbot/service.py): `apps/api/app/room_service/chatbot/service.py`
- [Answer agents](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/chatbot/agents.py): `apps/api/app/room_service/chatbot/agents.py`
- [AI providers](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/chatbot/providers.py): `apps/api/app/room_service/chatbot/providers.py`
- [Risk assessment](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/risk/service.py): `apps/api/app/room_service/risk/service.py`
- [Risk scoring](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/risk/scoring.py): `apps/api/app/room_service/risk/scoring.py`
- [Risk repository](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/risk/repo.py): `apps/api/app/room_service/risk/repo.py`
- [Reports service](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/reports/service.py): `apps/api/app/reports/service.py`

### Legal knowledge

- [Legal retrieval](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/chatbot/legal_retrieval.py): `apps/api/app/room_service/chatbot/legal_retrieval.py`
- [Legal ingestion](https://github.com/phucbeo223/local-project-for-student-room/blob/main/apps/api/app/room_service/legal_knowledge/ingestion.py): `apps/api/app/room_service/legal_knowledge/ingestion.py`

### Other components

- **Student**
- **AI providers**

## Connections

- Student → Web application: uses (evidence: `README.md`)
- API entry → Listing search: registers routes (evidence: `apps/api/app/main.py`)
- API entry → Chat API: registers routes (evidence: `apps/api/app/main.py`)
- API entry → Engagement: registers routes (evidence: `apps/api/app/main.py`)
- API entry → Authentication: registers routes (evidence: `apps/api/app/main.py`)
- API entry → Listing crawler: runs source (evidence: `apps/api/app/main.py`)
- API entry → Listing cleaner: runs cleaning (evidence: `apps/api/app/main.py`)
- Listing crawler → Listing repository: persists listings
- Listing crawler → Listing cleaner: normalizes input
- Listing cleaner → Listing repository: cleans records
- Listing search → Listing repository: queries listings (evidence: `apps/api/app/listings/router.py`)
- Listing search → Risk assessment: assesses risk (evidence: `apps/api/app/listings/router.py`)
- Authentication → Account lifecycle: manages accounts (evidence: `apps/api/app/auth/router.py`)
- Engagement → Engagement service: calls (evidence: `apps/api/app/engagement/router.py`)
- Engagement → Recommendations: ranks candidates (evidence: `apps/api/app/engagement/router.py`)
- Chat API → Chat orchestration: dispatches requests (evidence: `apps/api/app/room_service/chatbot/router.py`)
- Chat API → Answer agents: dispatches agents (evidence: `apps/api/app/room_service/chatbot/router.py`)
- Chat orchestration → AI providers: generates answers (evidence: `apps/api/app/room_service/chatbot/service.py`)
- Chat orchestration → Legal retrieval: retrieves law (evidence: `apps/api/app/room_service/chatbot/service.py`)
- AI providers → AI providers: calls provider
- Legal ingestion → Legal retrieval: supplies corpus
- Risk assessment → Risk scoring: scores listings (evidence: `apps/api/app/room_service/risk/service.py`)
- Risk assessment → Risk repository: loads and saves (evidence: `apps/api/app/room_service/risk/service.py`)
- Reports service → Risk assessment: assesses reports (evidence: `apps/api/app/reports/service.py`)
