Legal Property Platform

Legal Practice Management Platform — Developer Brief Project Overview We're building a web-based practice management platform for a licensed legal practice specialising in residential property transactions in Australia. The platform manages matters (cases) end-to-end: client intake, document management, task tracking, compliance checks, AI-powered document analysis, real-time messaging, and settlement preparation. The platform serves three user types with three separate interfaces sharing one database. Scope Note This brief covers the technical build requirements only. Domain-specific workflow logic will be provided during development via detailed step-by-step specifications. The developer does not need prior conveyancing knowledge — all process rules will be supplied. Tech Stack (Non-Negotiable) Layer Technology Frontend Next.js 14 (App Router), TypeScript Styling Tailwind CSS UI Components shadcn/ui Database Supabase (PostgreSQL) — Sydney region (ap-southeast-2) Auth Supabase Auth File Storage Supabase Storage Real-time Supabase Realtime AI AI Provider API (Messages API, server-side only) Email Resend SMS Twilio Hosting Vercel The Three Interfaces 1. Client Portal (/) Access method: No account or password. Client enters a reference number and their last name. If the combination matches a record, they see their matter. Session stored in a secure cookie. Features: Matter header: property address, key dates, reference number 9-step progress tracker: visual progress bar showing completed (green), current (blue), and upcoming (grey) steps. Steps are configurable — we will provide the specific step labels. Document upload area: client uploads files with a type selector from a predefined list. Shows a checklist of what's been received vs still needed. Messaging: iMessage-style chat thread. Client can send messages and see replies from staff with role labels. Real-time updates via Supabase Realtime. Notifications: alerts when matter advances a stage, when a document is uploaded by staff, when they receive a new message. Action buttons: configurable per-stage client actions (e.g. "Upload document X", "Confirm status Y"). These trigger matter updates when completed. UX rules: Mobile-responsive as primary design target No legal jargon in UI — plain English labels Must never expose internal staff views or navigation Dead simple — assume a first-time user who has never used anything like this 2. Staff Dashboard — Operations (/operations) Access method: Email and password via Supabase Auth. Route-protected. Features: Task list across all active matters, sorted by urgency relative to each matter's key deadline Tasks colour-coded: red = overdue, amber = due within 3 days, green = on track Grouped by matter — all tasks for one matter visible together Mark tasks complete with optimistic UI update Show/hide completed tasks toggle Badge counts per matter for unread messages and new tasks since last visit Matter detail view: all tasks, read-only message thread, read-only document list Cannot send client-facing messages (communicates via tasks only) 3. Staff Dashboard — Review (/dashboard) Access method: Email and password via Supabase Auth. Route-protected. This role can access both /dashboard and /operations. Features: Summary cards: total active matters, matters needing attention (overdue/blocked tasks), matters with key deadlines this week, matters with key deadlines next week Matter table: all active matters sorted by key deadline. Columns: reference address, client name, current stage (coloured badge), key deadline date, assigned operations staff, attention flag (warning icon if overdue/blocked tasks). Red row highlighting for overdue matters. Badge counts for unread items. Create new matter: form that creates a matter, generates a reference number (prefix + sequential 5-digit number), creates the client user record, and generates a default task list — all in one action. Fields will be specified. Matter detail page: Matter header with all matter info 9-step progress tracker with "Move to Next Stage" button (confirmation modal) Tasks panel: all tasks / my tasks filter, mark complete, add new tasks Document checklist with upload and download (signed URLs from Supabase Storage) Messaging panel: full message thread, send and receive, real-time updates, sender name and role displayed AI Reviews section: displays structured AI analysis outputs with status (pending review / approved / rejected) and approve/reject actions Compliance section: displays compliance check results with status indicators (not started / in progress / complete / flagged) Authentication Model Staff (two roles): Email/password via Supabase Auth Role stored in users table linked by auth_id Role determines which routes are accessible Middleware-based route protection Clients: No auth account Access via reference_number + last_name Session cookie with matter_id, validated against database on every request Portal API routes validate the session cookie before any read/write Database Schema Core Tables organisations id (UUID, PK) name (text) abn (text, nullable) created_at, updated_at users id (UUID, PK) auth_id (UUID, links to Supabase Auth — nullable for clients) organisation_id (UUID, FK → organisations) email (text) first_name, last_name (text) phone (text, nullable) role (text: 'client', 'operations', 'reviewer', 'admin') created_at, updated_at matters id (UUID, PK) reference_number (text, unique, auto-generated) organisation_id (UUID, FK → organisations) client_id (UUID, FK → users) operations_user_id (UUID, FK → users, nullable) reviewer_id (UUID, FK → users) primary_address (text) matter_type (text) property_type (text: 'freehold', 'strata') transaction_type (text: 'purchase', 'sale') key_amount (numeric) deposit_amount (numeric, nullable) current_stage (text — from configurable stage list) key_deadline (date, nullable) secondary_date (date, nullable) tertiary_date (date, nullable) client_last_name (text — used for portal access) status (text: 'active', 'completed', 'cancelled') metadata (jsonb, nullable — flexible field for additional matter-specific data) created_at, updated_at matter_stages id (UUID, PK) matter_id (UUID, FK → matters) stage (text) entered_at (timestamp) completed_at (timestamp, nullable) advanced_by (UUID, FK → users, nullable) tasks id (UUID, PK) matter_id (UUID, FK → matters) title (text) description (text, nullable) assigned_role (text: 'ai', 'operations', 'reviewer') status (text: 'pending', 'in_progress', 'completed', 'blocked') due_date (date, nullable) completed_at (timestamp, nullable) completed_by (UUID, FK → users, nullable) sort_order (integer) created_at, updated_at ai_reviews id (UUID, PK) matter_id (UUID, FK → matters) review_type (text — configurable) source_document_id (UUID, FK → documents, nullable) input_data (jsonb) output_data (jsonb — structured AI response) risk_flags (jsonb — array of severity, field, description) confidence_score (numeric, nullable) tokens_used (integer) estimated_cost (numeric) status (text: 'pending_review', 'approved', 'rejected', 'superseded') reviewed_by (UUID, FK → users, nullable) reviewed_at (timestamp, nullable) reviewer_notes (text, nullable) created_at documents id (UUID, PK) matter_id (UUID, FK → matters) file_name (text) file_path (text — Supabase Storage path) file_size (integer, nullable) mime_type (text, nullable) document_type (text — from configurable document type list) uploaded_by (UUID, FK → users) created_at messages id (UUID, PK) matter_id (UUID, FK → matters) sender_id (UUID, FK → users) sender_role (text) content (text) is_read (boolean, default false) created_at notifications id (UUID, PK) user_id (UUID, FK → users) matter_id (UUID, FK → matters, nullable) type (text — configurable) title (text) body (text) is_read (boolean, default false) created_at matter_views id (UUID, PK) user_id (UUID, FK → users) matter_id (UUID, FK → matters) last_viewed_at (timestamp) Unique constraint on (user_id, matter_id) compliance_checks id (UUID, PK) matter_id (UUID, FK → matters) client_id (UUID, FK → users) check_type (text — configurable, e.g. 'identity_verification', 'screening', 'risk_assessment') provider (text, nullable) result (text: 'clear', 'match', 'potential_match', 'pending', 'failed') risk_rating (text: 'low', 'medium', 'high', nullable) raw_response (jsonb — full API response for audit) checked_by (UUID, FK → users) created_at notes (text, nullable) trust_ledger id (UUID, PK) matter_id (UUID, FK → matters) transaction_date (date) description (text) amount (numeric — positive for money in, negative for money out) transaction_type (text: 'receipt', 'payment', 'transfer', 'fee_deduction', 'refund') authorised_by (UUID, FK → users — must be reviewer role) authorised_at (timestamp) reference (text, nullable — bank reference, receipt number etc.) running_balance (numeric) created_at notes (text, nullable) Row Level Security RLS must be enabled on every table: Clients can only see rows linked to their own matter Operations users can only see rows for matters assigned to them Reviewers can see all rows within their organisation Trust ledger: reviewer role only (operations users cannot read or write) Compliance checks: reviewer can read/write, operations can read only, clients cannot access AI Layer Requirements Architecture All AI API calls happen server-side via Next.js API routes — never from client-side browser code AI Provider API key stored in environment variables, never exposed to browser Every AI call must be logged: input, output, tokens used, estimated cost — stored in ai_reviews table All AI output presented as a draft requiring human review — UI must include clear labels indicating this Prompts stored centrally in /src/lib/ai/ — never inline in components or API routes Set appropriate max_tokens limits per call type AI Agent 1: Document Analysis Input: PDF document uploaded to matter Process: Extract text from PDF. Send to AI Provider API with a structured system prompt. Return structured JSON output. Output: Structured JSON containing extracted fields (field list will be provided per document type), risk flags with severity (red/amber/green) and explanations, confidence scores per field. Edge cases: Scanned PDFs (OCR required), multi-part documents with annexures, varying document formats, handwritten amendments. AI Agent 2: Secondary Document Analysis Input: Various PDF documents (different types) Process: Identify document type, extract key fields per type, cross-reference against data already extracted from primary documents. Output: Per-document analysis plus consolidated summary with risk flags. AI Agent 3: Financial Calculator Input: Rate amounts extracted from documents, key dates, rating periods Process: Calculate daily rates and pro-rate between parties based on date. Output: Itemised calculation sheet with line items and net figure. Note: The actual arithmetic should be deterministic code, not AI inference. AI is used for extracting values from documents — the calculation itself must be precise. AI Agent 4: Correspondence Drafter Input: Brief instructions from reviewer (e.g. "advise client results are clean, no issues found") Process: Generate professional correspondence in plain English. Output: Draft for reviewer approval before sending. Tone: Professional but approachable. No jargon. Reader is typically a first-time user. Notification System In-App Notifications Badge count in navigation Dropdown showing unread notifications Mark as read on click Triggered by: stage changes, new messages, document uploads, overdue tasks, AI review ready, compliance check results Email Notifications (Resend) Stage advancement → notify client New message → notify recipient Document uploaded → notify reviewer Task overdue → notify assigned role Templated emails with matter context SMS Notifications (Twilio) Key deadline reminders (T-7 days, T-2 days, T-1 day) Urgent alerts (overdue compliance, failed checks) Trust Ledger Module The platform tracks financial movements per matter. It does NOT integrate with banking — it is a ledger only. The actual bank account is managed separately. Features: Per-matter trust account view: all transactions, running balance, expected vs actual Overall trust summary: combined balance across all matters Reviewer-only authorisation on every transaction (operations staff cannot authorise) Monthly reconciliation sign-off by reviewer End-of-matter trust statement: auto-generated summary of all movements No deletion of trust records — ever. Corrections made via offsetting entries. All trust records retained for minimum 7 years No hard-delete capability on trust data Stage Automation Stages can auto-advance when certain conditions are met. The reviewer can also manually advance or reverse stages. Automation rules will be provided as a configuration — the platform should support rule-based stage advancement where rules are defined as: "when all tasks with tag X are completed, advance to stage Y." Security Requirements All client data stored in Supabase Sydney region (ap-southeast-2) Row Level Security on every table Document storage bucket with restricted access (signed URLs, expiring) No client data in URL parameters Session cookies: secure, httpOnly, sameSite strict Validate all user input on client and server side Sanitise file uploads (check types, limit sizes) Environment variables for all API keys and secrets Every AI call, document access, stage change, and login logged with timestamp and user All logs and records retained for minimum 7 years Audit trail: who did what, when, to which matter File/Folder Structure /src /app page.tsx — Client portal access form /auth/login — Staff login /portal — Client portal pages /operations — Operations dashboard pages /dashboard — Reviewer dashboard pages /matters/[id] — Matter detail page /api /ai — AI agent endpoints /matters — Matter CRUD /notifications — Notification endpoints /portal — Portal access/signout /trust — Trust ledger endpoints /components /ui — shadcn/ui base components /matters — Matter-specific components /portal — Client portal components /operations — Operations dashboard components /dashboard — Reviewer dashboard components /lib /supabase — Supabase client configuration /ai — AI prompt templates and helpers /utils — General utilities /types — TypeScript type definitions middleware.ts — Route protection /public — Static assets /supabase — Database migrations Deliverables & Milestones Milestone 1: Foundation + Auth + Security Next.js 14 project with Tailwind + shadcn/ui Supabase connected (Sydney region) Authentication working (staff login + client portal access) Route protection via middleware Database tables created with proper RLS policies All three interfaces with basic layouts Milestone 2: Core Platform Matter creation with auto-generated reference numbers and default task lists Matter detail page with progress tracker, tasks, documents, messaging Operations dashboard with task list, urgency sorting, mark complete Reviewer dashboard with summary cards, matter table, attention flags Client portal with progress tracker, document upload, messaging Supabase Realtime for messaging Document upload/download with signed URLs Milestone 3: AI Layer + Notifications AI document analysis (PDF upload → structured JSON output) AI secondary document analysis with cross-referencing AI financial calculator AI correspondence drafter In-app notification system Email notifications via Resend SMS notifications via Twilio Milestone 4: Compliance + Trust + Polish Compliance check workflow (identity verification, screening, risk assessment) Compliance hard gate (matters cannot advance without completed checks) Trust ledger module with reviewer-only authorisation Trust reconciliation view Stage automation rules engine Mobile responsiveness audit Landing/marketing page Security audit and final testing Budget & Terms Fixed-price engagement, milestone-based payments. Payment on delivery and confirmation of each milestone. What We Provide Detailed domain-specific workflow documentation (provided after engagement, under NDA) AI prompt specifications and system prompts Configurable stage labels, task templates, and document type lists Access to Supabase project, Vercel, and all API keys Responsive communication and feedback within 24 hours on all deliverables