# lihancancode/thikanaai architecture

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

- Interactive diagram: https://gitdiagram.com/lihancancode/thikanaai
- Repository: https://github.com/lihancancode/thikanaai

## Overview

1. **Overall shape**
   Thikana AI is a single Next.js 15 App Router application that combines the UI, backend endpoints, and server-side business logic in one repo. There is no separate standalone API service; instead, the backend boundary is split between **server actions** and **route handlers** under `src/app`.

2. **Primary runtime and persistence**
   The application is built around **Supabase** for authentication, PostgreSQL data, and likely storage. Client-side code uses Supabase’s browser client, while privileged operations use dedicated server/admin clients from `src/lib/supabase`. The database schema is versioned in `supabase/migrations`, so the schema is an important architectural boundary.

3. **User-facing product areas**
   The app is organized by top-level product flows: `listings`, `student`, `landlord`, `alerts`, `chat`, `profile`, `dashboard`, `admin`, and auth pages. This indicates a marketplace plus tenant/student utility platform, not just a simple listings site. The landing page and shared layout sit in `src/app/page.tsx` and `src/app/layout.tsx`.

4. **Marketplace and listing flow**
   Listing browsing lives in `src/app/listings`, with detail pages, a new-listing flow, estimation tools, and a family-related sub-area. Reusable listing UI is in `src/components/listings` and `src/components/cards`. Listing search is exposed through `src/app/api/listings/search`, which is the main data-access path for marketplace discovery.

5. **AI subsystem**
   The AI features are concentrated in `src/app/api/ai/*`. Separate endpoints handle **listing generation**, **flatmate matching**, **neighborhood Q&A**, **query parsing**, **photo scoring**, **rent estimation**, and **trust scoring**. This suggests AI is not a single model integration, but a set of narrow, task-specific services layered on top of Gemini.

6. **Trust, fraud, and image analysis**
   Fraud detection is a dedicated subsystem. `src/lib/image-hash.ts` and `src/app/api/utils/hash-photos` support hashing photos, while `src/app/actions/ai-trust-score.ts` and `src/app/api/ai/trust-score` compute listing trust signals. The related migrations add `photo_hashes` and `trust_scores`, so image verification and score persistence are first-class parts of the architecture.

7. **Student matching and shared-living flows**
   The `student` area is a separate domain with its own pages for feed, finance, matching, room shares, and a student-specific Flick API route. Supporting logic lives in `src/lib/flatmate-candidates.ts`, `src/lib/flatmate-db.ts`, and student-specific action files. This domain likely reads from Supabase, applies compatibility logic, and then surfaces matches/results in the student UI.

8. **Alerts and notifications**
   Saved search alerts are handled by both UI and API: `src/app/alerts`, `src/app/api/alerts/save`, and `src/app/api/alerts/[id]`. The `005_chat_and_notifications.sql` migration indicates notifications and chat are persisted features rather than purely client-side state. This area is the user-facing layer for ongoing match notifications.

9. **Auth, roles, and privileged operations**
   Authentication is centered in `src/app/auth` and supported by `src/lib/auth-utils.ts` plus Supabase middleware/server helpers. The presence of `src/app/api/make-admin` and `007_admin_verification.sql` shows role elevation is controlled server-side. The middleware file is important for session handling and request gating at the edge.

10. **External integrations and utility layers**
   Gemini integration is centralized in `src/lib/gemini.ts`; Mapbox is abstracted in `src/lib/mapbox.ts`; image processing and hashing utilities support server-side media analysis. Shared UI primitives live in `src/components/ui`, layout/navigation in `src/components/layout` and `src/components/shared`, and animations/providers in `src/lib/animations` plus `src/components/providers`. These are supporting layers rather than domain boundaries.

11. **Operational boundaries**
   Security and request-shaping happen at the edge via `src/middleware.ts`, while global presentation setup is in `next.config.ts`, `src/app/globals.css`, and Tailwind/PostCSS config. Seed data utilities in `src/lib/seed-listings.ts` and `src/lib/seed-profiles.ts` suggest local bootstrapping/testing support. Overall, the repo is a layered monolith: UI routes on top, server actions/route handlers in the middle, and Supabase/Gemini/Mapbox as external dependencies.

Main entry points: [`src/app/api/ai/generate-listing/route.ts`](https://github.com/lihancancode/thikanaai/blob/main/src/app/api/ai/generate-listing/route.ts) (AI services), [`src/lib/supabase/client.ts`](https://github.com/lihancancode/thikanaai/blob/main/src/lib/supabase/client.ts) (Supabase clients), [`src/app/listings/page.tsx`](https://github.com/lihancancode/thikanaai/blob/main/src/app/listings/page.tsx) (Listings), [`src/app/actions/ai-trust-score.ts`](https://github.com/lihancancode/thikanaai/blob/main/src/app/actions/ai-trust-score.ts) (Server actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Router"]
  node_layout["App shell<br/>next layout<br/>[layout.tsx]"]
  node_home["Landing<br/>marketing page<br/>[page.tsx]"]
  node_listings["Listings<br/>marketplace page<br/>[page.tsx]"]
  node_listing_detail["Listing detail<br/>detail page<br/>[page.tsx]"]
  node_listing_new["New listing<br/>creation page<br/>[page.tsx]"]
  node_listing_estimate["Estimate<br/>pricing page<br/>[page.tsx]"]
  node_student_home["Student hub<br/>student page<br/>[page.tsx]"]
  node_student_match["Matching<br/>student flow<br/>[page.tsx]"]
  node_alerts["Alerts<br/>notification page<br/>[page.tsx]"]
  node_chat["Chat<br/>messaging page<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>overview page<br/>[page.tsx]"]
  node_profile["Profile<br/>account page<br/>[page.tsx]"]
  node_landlord_dash["Landlord<br/>[page.tsx]"]
  node_admin["Admin<br/>[page.tsx]"]
  node_api_listings_search["Search API<br/>route handler<br/>[route.ts]"]
  node_api_ai["AI services<br/>route handlers<br/>[route.ts]"]
  node_api_alerts["Alerts API<br/>route handlers<br/>[route.ts]"]
  node_api_admin["Admin API<br/>route handler<br/>[route.ts]"]
  node_server_actions["Server actions<br/>action layer<br/>[ai-trust-score.ts]"]
  node_student_api["Student API<br/>route handler<br/>[route.ts]"]
end

subgraph group_lib["Shared Logic"]
  node_supabase_client[("Supabase clients<br/>db clients<br/>[client.ts]")]
  node_auth_utils["Auth utils<br/>auth helpers<br/>[auth-utils.ts]"]
  node_gemini["Gemini<br/>ai integration<br/>[gemini.ts]"]
  node_flatmate_logic["Flatmate logic<br/>matching logic"]
  node_image_hash["Image hash<br/>media verification<br/>[image-hash.ts]"]
  node_mapbox["Mapbox<br/>maps integration<br/>[mapbox.ts]"]
end

subgraph group_components["UI Components"]
  node_listing_cards["Listing UI<br/>presentational components<br/>[ListingCard.tsx]"]
  node_layout_ui["Layout UI<br/>navigation components<br/>[Navbar.tsx]"]
  node_shared_ui["Shared UI<br/>primitive components<br/>[GreenButton.tsx]"]
end

subgraph group_data["Supabase"]
  node_schema[("Schema<br/>postgres migrations")]
end

node_layout -->|"renders"| node_home
node_layout -->|"frames"| node_listings
node_layout -->|"frames"| node_student_home
node_layout -->|"frames"| node_dashboard
node_listings -->|"searches"| node_api_listings_search
node_listings -->|"opens"| node_listing_detail
node_listings -->|"creates"| node_listing_new
node_listings -->|"estimates"| node_listing_estimate
node_listing_new -->|"generates"| node_api_ai
node_listing_detail -->|"scores"| node_api_ai
node_listing_detail -->|"uses"| node_listing_cards
node_listing_estimate -->|"estimates"| node_api_ai
node_student_home -->|"routes to"| node_student_match
node_student_match -->|"matches"| node_flatmate_logic
node_student_match -->|"integrates"| node_student_api
node_alerts -->|"manages"| node_api_alerts
node_chat -->|"mutates"| node_server_actions
node_profile -->|"updates"| node_server_actions
node_landlord_dash -->|"operates"| node_server_actions
node_admin -->|"administers"| node_api_admin
node_api_ai -->|"calls"| node_gemini
node_api_ai -->|"reads/writes"| node_supabase_client
node_server_actions -->|"persists"| node_supabase_client
node_server_actions -->|"checks"| node_auth_utils
node_auth_utils -->|"auths"| node_supabase_client
node_api_alerts -->|"stores"| node_supabase_client
node_api_listings_search -->|"queries"| node_supabase_client
node_api_admin -->|"gates"| node_auth_utils
node_image_hash -->|"supports"| node_api_ai
node_image_hash -->|"persists"| node_schema
node_flatmate_logic -->|"reads/writes"| node_schema
node_supabase_client -->|"targets"| node_schema
node_shared_ui -->|"supports"| node_layout_ui
node_listing_cards -->|"composes"| node_shared_ui

click node_layout "https://github.com/lihancancode/thikanaai/blob/main/src/app/layout.tsx"
click node_home "https://github.com/lihancancode/thikanaai/blob/main/src/app/page.tsx"
click node_listings "https://github.com/lihancancode/thikanaai/blob/main/src/app/listings/page.tsx"
click node_listing_detail "https://github.com/lihancancode/thikanaai/blob/main/src/app/listings/[id]/page.tsx"
click node_listing_new "https://github.com/lihancancode/thikanaai/blob/main/src/app/listings/new/page.tsx"
click node_listing_estimate "https://github.com/lihancancode/thikanaai/blob/main/src/app/listings/estimate/page.tsx"
click node_student_home "https://github.com/lihancancode/thikanaai/blob/main/src/app/student/page.tsx"
click node_student_match "https://github.com/lihancancode/thikanaai/blob/main/src/app/student/matching/page.tsx"
click node_alerts "https://github.com/lihancancode/thikanaai/blob/main/src/app/alerts/page.tsx"
click node_chat "https://github.com/lihancancode/thikanaai/blob/main/src/app/chat/page.tsx"
click node_dashboard "https://github.com/lihancancode/thikanaai/blob/main/src/app/dashboard/page.tsx"
click node_profile "https://github.com/lihancancode/thikanaai/blob/main/src/app/profile/page.tsx"
click node_landlord_dash "https://github.com/lihancancode/thikanaai/blob/main/src/app/landlord/dashboard/page.tsx"
click node_admin "https://github.com/lihancancode/thikanaai/blob/main/src/app/admin/page.tsx"
click node_api_listings_search "https://github.com/lihancancode/thikanaai/blob/main/src/app/api/listings/search/route.ts"
click node_api_ai "https://github.com/lihancancode/thikanaai/blob/main/src/app/api/ai/generate-listing/route.ts"
click node_api_alerts "https://github.com/lihancancode/thikanaai/blob/main/src/app/api/alerts/save/route.ts"
click node_api_admin "https://github.com/lihancancode/thikanaai/blob/main/src/app/api/make-admin/route.ts"
click node_server_actions "https://github.com/lihancancode/thikanaai/blob/main/src/app/actions/ai-trust-score.ts"
click node_student_api "https://github.com/lihancancode/thikanaai/blob/main/src/app/student/flick-api/route.ts"
click node_supabase_client "https://github.com/lihancancode/thikanaai/blob/main/src/lib/supabase/client.ts"
click node_auth_utils "https://github.com/lihancancode/thikanaai/blob/main/src/lib/auth-utils.ts"
click node_gemini "https://github.com/lihancancode/thikanaai/blob/main/src/lib/gemini.ts"
click node_flatmate_logic "https://github.com/lihancancode/thikanaai/blob/main/src/lib/flatmate-candidates.ts"
click node_image_hash "https://github.com/lihancancode/thikanaai/blob/main/src/lib/image-hash.ts"
click node_mapbox "https://github.com/lihancancode/thikanaai/blob/main/src/lib/mapbox.ts"
click node_schema "https://github.com/lihancancode/thikanaai/blob/main/supabase/migrations/001_initial_schema.sql"
click node_listing_cards "https://github.com/lihancancode/thikanaai/blob/main/src/components/listings/ListingCard.tsx"
click node_layout_ui "https://github.com/lihancancode/thikanaai/blob/main/src/components/layout/Navbar.tsx"
click node_shared_ui "https://github.com/lihancancode/thikanaai/blob/main/src/components/ui/GreenButton.tsx"

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_layout,node_home,node_listings,node_listing_detail,node_listing_new,node_listing_estimate,node_student_home,node_student_match,node_alerts,node_chat,node_dashboard,node_profile,node_landlord_dash,node_admin,node_api_listings_search,node_api_ai,node_api_alerts,node_api_admin,node_server_actions,node_student_api toneBlue
class node_supabase_client,node_auth_utils,node_gemini,node_flatmate_logic,node_image_hash,node_mapbox toneAmber
class node_listing_cards,node_layout_ui,node_shared_ui toneMint
class node_schema toneRose
```

## Components

### App Router

Next.js UI routes, server actions, and route handlers under src/app.

- [App shell](https://github.com/lihancancode/thikanaai/blob/main/src/app/layout.tsx): next layout · Global document shell, navigation, and shared app scaffolding. · `src/app/layout.tsx`
- [Landing](https://github.com/lihancancode/thikanaai/blob/main/src/app/page.tsx): marketing page · Public entry point and overview of the product. · `src/app/page.tsx`
- [Listings](https://github.com/lihancancode/thikanaai/blob/main/src/app/listings/page.tsx): marketplace page · Browse and search listings, with item detail and creation flows nearby. · `src/app/listings/page.tsx`
- [Listing detail](https://github.com/lihancancode/thikanaai/blob/main/src/app/listings/[id]/page.tsx): detail page · Single listing view and associated discovery actions. · `src/app/listings/[id]/page.tsx`
- [New listing](https://github.com/lihancancode/thikanaai/blob/main/src/app/listings/new/page.tsx): creation page · Flow for creating or generating a new listing. · `src/app/listings/new/page.tsx`
- [Estimate](https://github.com/lihancancode/thikanaai/blob/main/src/app/listings/estimate/page.tsx): pricing page · Rent estimation and listing valuation surface. · `src/app/listings/estimate/page.tsx`
- [Student hub](https://github.com/lihancancode/thikanaai/blob/main/src/app/student/page.tsx): student page · Student-facing entry point for matching and shared-living features. · `src/app/student/page.tsx`
- [Matching](https://github.com/lihancancode/thikanaai/blob/main/src/app/student/matching/page.tsx): student flow · Compatibility, feeds, and match results for student users. · `src/app/student/matching/page.tsx`
- [Alerts](https://github.com/lihancancode/thikanaai/blob/main/src/app/alerts/page.tsx): notification page · Saved searches and notification management. · `src/app/alerts/page.tsx`
- [Chat](https://github.com/lihancancode/thikanaai/blob/main/src/app/chat/page.tsx): messaging page · User messaging and conversation surface. · `src/app/chat/page.tsx`
- [Dashboard](https://github.com/lihancancode/thikanaai/blob/main/src/app/dashboard/page.tsx): overview page · General authenticated dashboard. · `src/app/dashboard/page.tsx`
- [Profile](https://github.com/lihancancode/thikanaai/blob/main/src/app/profile/page.tsx): account page · User profile and account settings surface. · `src/app/profile/page.tsx`
- [Landlord](https://github.com/lihancancode/thikanaai/blob/main/src/app/landlord/dashboard/page.tsx): landlord dashboard · Landlord-facing dashboard and operational actions. · `src/app/landlord/dashboard/page.tsx`
- [Admin](https://github.com/lihancancode/thikanaai/blob/main/src/app/admin/page.tsx): admin page · Administrative control surface. · `src/app/admin/page.tsx`
- [Search API](https://github.com/lihancancode/thikanaai/blob/main/src/app/api/listings/search/route.ts): route handler · Primary listing discovery endpoint. · `src/app/api/listings/search/route.ts`
- [AI services](https://github.com/lihancancode/thikanaai/blob/main/src/app/api/ai/generate-listing/route.ts): route handlers · Task-specific AI endpoints for listings, matching, Q&A, parsing, scoring, and estimation. · `src/app/api/ai/generate-listing/route.ts`
- [Alerts API](https://github.com/lihancancode/thikanaai/blob/main/src/app/api/alerts/save/route.ts): route handlers · Save, fetch, and manage alert records. · `src/app/api/alerts/save/route.ts`
- [Admin API](https://github.com/lihancancode/thikanaai/blob/main/src/app/api/make-admin/route.ts): route handler · Server-side role elevation and admin control. · `src/app/api/make-admin/route.ts`
- [Server actions](https://github.com/lihancancode/thikanaai/blob/main/src/app/actions/ai-trust-score.ts): action layer · Server-side mutations for trust scoring, chat, auth, profile, landlord, and student workflows. · `src/app/actions/ai-trust-score.ts`
- [Student API](https://github.com/lihancancode/thikanaai/blob/main/src/app/student/flick-api/route.ts): route handler · Student-specific integration endpoint. · `src/app/student/flick-api/route.ts`

### Shared Logic

Reusable server/client helpers and domain logic in src/lib.

- [Supabase clients](https://github.com/lihancancode/thikanaai/blob/main/src/lib/supabase/client.ts): db clients · Browser, server, admin, and middleware Supabase helpers. · `src/lib/supabase/client.ts`
- [Auth utils](https://github.com/lihancancode/thikanaai/blob/main/src/lib/auth-utils.ts): auth helpers · Session, role, and request-auth helper logic. · `src/lib/auth-utils.ts`
- [Gemini](https://github.com/lihancancode/thikanaai/blob/main/src/lib/gemini.ts): ai integration · Central Gemini model integration used by AI endpoints. · `src/lib/gemini.ts`
- [Flatmate logic](https://github.com/lihancancode/thikanaai/blob/main/src/lib/flatmate-candidates.ts): matching logic · Candidate selection, compatibility, and persistence helpers for student matching. · `src/lib/flatmate-candidates.ts`
- [Image hash](https://github.com/lihancancode/thikanaai/blob/main/src/lib/image-hash.ts): media verification · Photo hashing and trust-related image analysis support. · `src/lib/image-hash.ts`
- [Mapbox](https://github.com/lihancancode/thikanaai/blob/main/src/lib/mapbox.ts): maps integration · Geospatial and map-related helper integration. · `src/lib/mapbox.ts`

### UI Components

Shared presentation components used across product flows.

- [Listing UI](https://github.com/lihancancode/thikanaai/blob/main/src/components/listings/ListingCard.tsx): presentational components · Listing cards, maps, and marketplace presentation pieces. · `src/components/listings/ListingCard.tsx`
- [Layout UI](https://github.com/lihancancode/thikanaai/blob/main/src/components/layout/Navbar.tsx): navigation components · Shared navbar and page-level layout elements. · `src/components/layout/Navbar.tsx`
- [Shared UI](https://github.com/lihancancode/thikanaai/blob/main/src/components/ui/GreenButton.tsx): primitive components · Reusable buttons, animations, and provider wrappers. · `src/components/ui/GreenButton.tsx`

### Supabase

Database schema, migrations, and Supabase client helpers.

- [Schema](https://github.com/lihancancode/thikanaai/blob/main/supabase/migrations/001_initial_schema.sql): postgres migrations · Versioned Supabase/PostgreSQL schema and storage configuration. · `supabase/migrations/001_initial_schema.sql`

## Connections

- App shell → Landing: renders · App shell frames the public landing page.
- App shell → Listings: frames · Global shell supports marketplace pages.
- App shell → Student hub: frames · Global shell supports student flows.
- App shell → Dashboard: frames · Global shell supports authenticated dashboards.
- Listings → Search API: searches · Marketplace browsing is backed by the search endpoint.
- Listings → Listing detail: opens · Listings index links into item detail views.
- Listings → New listing: creates · Marketplace supports listing creation.
- Listings → Estimate: estimates · Discovery flow connects to rent estimation.
- New listing → AI services: generates · New listing flow uses AI generation services.
- Listing detail → AI services: scores · Detail view can call AI-backed enrichment and trust functions.
- Listing detail → Listing UI: uses · Detail and browse surfaces share listing presentation components.
- Estimate → AI services: estimates · Rent estimation is delegated to AI services.
- Student hub → Matching: routes to · Student hub leads into matching and feed flows.
- Matching → Flatmate logic: matches · Student matching depends on compatibility helpers.
- Matching → Student API: integrates · Student-specific endpoint supports the matching experience.
- Alerts → Alerts API: manages · Saved alerts are persisted through route handlers.
- Chat → Server actions: mutates · Chat interactions are handled by server-side actions.
- Profile → Server actions: updates · Profile edits use server actions.
- Landlord → Server actions: operates · Landlord dashboard mutations are server-side.
- Admin → Admin API: administers · Admin page uses privileged admin control endpoints.
- AI services → Gemini: calls · AI routes centralize on Gemini integration.
- AI services → Supabase clients: reads/writes · AI outputs and related state are persisted through Supabase helpers.
- Server actions → Supabase clients: persists · Server mutations use privileged Supabase access.
- Server actions → Auth utils: checks · Action layer relies on auth and role helpers.
- Auth utils → Supabase clients: auths · Authentication helpers wrap Supabase session handling.
- Alerts API → Supabase clients: stores · Alerts are stored in Supabase.
- Search API → Supabase clients: queries · Search is backed by database access.
- Admin API → Auth utils: gates · Role elevation is gated by server-side auth logic.
- Image hash → AI services: supports · Image verification underpins trust and photo scoring flows.
- Image hash → Schema: persists · Photo hashes and trust scores are schema-backed features.
- Flatmate logic → Schema: reads/writes · Student matching logic is persisted in the database schema.
- Supabase clients → Schema: targets · All Supabase clients point at the versioned PostgreSQL schema.
- Shared UI → Layout UI: supports · Shared primitives are composed by layout/navigation components.
- Listing UI → Shared UI: composes · Marketplace UI is built from shared primitives.