Project: Plano Realty CRM / LynkedUpPro Frontend: React 19 SPA (Vite + Tailwind + React Router v7) Target Backend: FastAPI + PostgreSQL + Alembic Deployment: Frontend on Vercel (static); Backend to be hosted separately (Railway, Render, or VPS)

Purpose

This docs/ folder is the technical contract between three teams:

Team	Role
Frontend	React SPA — already feature-complete with mock data
Backend	Builds the FastAPI server, database, and all API endpoints
Integration	Replaces mock data calls in the frontend with real API calls; writes tests

The docs are written module by module, approved one at a time, so each team always has a stable, reviewable spec before writing code.

Reading Guide

If you are on the Backend Team

Start with backend/00_project_overview.md, then read modules in order (B1 → B2 → B3 ...). The database schema (B2) is your single source of truth — read it before touching any other module.

If you are on the Integration Team

Start with integration/00_integration_overview.md. Each integration module (I1–I8) maps directly to a backend module (B1–B8) — read them as pairs.

If you are reviewing architecture

Start with diagrams/hld.md for the bird's-eye view, then diagrams/lld_architecture.md and diagrams/lld_database.md for detail. The prose docs (backend/00_* and backend/02_*) provide the full specification behind each diagram.

Diagram Index

Visual reference for architecture and database design. All diagrams use Mermaid and render natively in GitHub, GitLab, VS Code (with Mermaid extension), and Notion.

File	Diagrams Inside	Scope
`diagrams/hld.md`	System Context · Components · Role Access Zones · Data Flow · Deployment · RBAC Summary	Full system HLD
`diagrams/lld_architecture.md`	App Layer Structure · HTTP Request Lifecycle · Login Flow · Auth Request Flow · Token Refresh · RBAC Decision Tree · Module Build Order · Chatbot Context Builder · Env Config Flow	B0 LLD
`diagrams/lld_database.md`	Full ER Diagram (all 16 tables) · Meeting State Machine · Invoice State Machine · Project State Machine · Compliance State Machine · Soft Delete Pattern · Audit Log Pattern · Role-Scoped Queries · Legacy ID Migration	B2 LLD
`diagrams/lld_b1_authentication.md`	Auth File Dependency Graph · Password Hashing Lifecycle · JWT Token Anatomy · Login Type Decision Tree · Refresh Token Rotation + Reuse Attack · Cookie Security Config · Permission Matrix Decision Flow · Sensitive Data Masking · `get_current_user()` Dependency Resolution	B1 LLD
`diagrams/lld_i0_integration.md`	Frontend API Layer Architecture · 401 Interceptor State Machine · Mock-to-Real Migration Lifecycle · Feature Flag Decision Tree · Frontend Request Lifecycle · HTTP Error Handling Decision Tree · Env Variable Flow · `withCredentials` + CORS Handshake	I0 LLD
`diagrams/lld_i1_auth_integration.md`	Before/After AuthContext Architecture · AuthContext State Machine · Session Restore on Mount · Async Login Flow · Role Redirect Decision Tree · Async Logout Flow · Forced Logout Event Flow · ProtectedRoute Decision Tree · User Object Shape Transformation	I1 LLD

Proposals

Design decision documents that must be approved before their corresponding modules are written.

File	Topic	Status
`proposals/chatbot_ai_approach.md`	Chatbot AI approach — Tool Calling vs RAG vs GraphRAG, tool catalogue, RBAC, write confirmation, audit	🔲 Pending Approval

Module Index

Backend Team

File	Module	Status
`backend/00_project_overview.md`	B0 — Project Overview & API Conventions	✅ Complete
`backend/01_authentication_module.md`	B1 — JWT Auth, RBAC, All 6 Roles	✅ Complete
`backend/02_database_schema.md`	B2 — Full PostgreSQL Schema + ER Notes	✅ Complete
`backend/03_properties_module.md`	B3 — Properties CRUD, Geospatial, Lead Logic	🔲 Pending
`backend/04_users_people_module.md`	B4 — User Management, Masked Fields	🔲 Pending
`backend/05_meetings_scheduling_module.md`	B5 — Meetings CRUD, Status Machine, Change Requests	🔲 Pending
`backend/06_vendors_compliance_module.md`	B6 — Vendors, COI, Compliance Expiration Alerts	🔲 Pending
`backend/07_financial_module.md`	B7 — Invoices, AR/AP, Payout Approval Workflow	🔲 Pending
`backend/08_chatbot_ai_module.md`	B8 — RBAC Context Builder, Groq Proxy, Audit Logging	🔲 Pending
`backend/09_notifications_module.md`	B9 — Email Triggers, In-App Notifications, Alerts	🔲 Pending

Integration & Testing Team

File	Module	Status
`integration/00_integration_overview.md`	I0 — API Client Setup, Auth Tokens, Error Handling	✅ Complete
`integration/01_auth_integration.md`	I1 — Replace AuthContext Mock with Real JWT Flow	✅ Complete
`integration/02_data_layer_migration.md`	I2 — Remove MockStoreProvider, Create ApiProvider	🔲 Pending
`integration/03_properties_integration.md`	I3 — Map + Property Components → Real API	🔲 Pending
`integration/04_users_people_integration.md`	I4 — PeopleDirectory, VendorDirectory → Real API	🔲 Pending
`integration/05_meetings_integration.md`	I5 — AdminSchedule, Dashboard Meetings → Real API	🔲 Pending
`integration/06_vendors_compliance_integration.md`	I6 — Compliance Docs, Status Badges → Real API	🔲 Pending
`integration/07_financial_integration.md`	I7 — Invoice Tables, AR/AP, Payout Flows → Real API	🔲 Pending
`integration/08_chatbot_integration.md`	I8 — Live Context Fetch, Role Enforcement → Real API	🔲 Pending
`integration/09_testing_strategy.md`	I9 — Role Matrix, API Contract Tests, E2E, CI	🔲 Pending

Key Frontend Source Files

These are the primary files the Integration Team will be modifying:

File	What It Does
`src/data/mockStore.jsx`	The entire fake backend — will be replaced module by module
`src/context/AuthContext.jsx`	Client-side login — will be replaced with real JWT flow
`src/context/ThemeContext.jsx`	Theme only — no backend integration needed
`src/context/GamificationContext.jsx`	Gamification state — may be partially persisted to backend
`src/App.jsx`	Routes + ProtectedRoute — role logic may need JWT claims
`src/components/Chatbot.jsx`	Direct Groq SDK calls — will be proxied through backend

Conventions Used Across All Docs

API Base URL: http://localhost:8000/api/v1 (dev) / https://api.lynkeduppro.com/api/v1 (prod)
Auth: Bearer token in Authorization header. Token stored in httpOnly cookie (preferred) or localStorage (fallback).
Role names: OWNER, ADMIN, FIELD_AGENT, CONTRACTOR, SUBCONTRACTOR, VENDOR, CUSTOMER — exactly as they appear in the frontend AuthContext.
Date format: ISO 8601 (2026-02-24T14:30:00Z) for all timestamps.
Money: All monetary values in cents (integer) at the API layer; frontend divides by 100 for display.
Error responses: Standard shape { "detail": "Human-readable message", "code": "MACHINE_CODE" }.

Maintained by Satyam Rastogi — update module status as docs are completed.

README.md Unescape Escape

LynkedUpPro CRM — Backend & Integration Documentation