replit.md

South Australia Family Advocacy AI Platform

Overview

A legal technology platform specifically designed for South Australian families navigating child protection cases. The system analyzes case documents, identifies rights violations under SA legislation, and provides AI-powered legal guidance based on the Children and Young People (Safety) Act 2017 (SA) and related laws. The application combines document parsing, AI analysis using OpenAI's GPT models, and a comprehensive UI for case management and advocacy support.

Core Purpose: Empower South Australian parents in child protection cases by making legal analysis accessible, identifying procedural violations specific to SA law, and emphasizing family preservation principles. The platform advocates strongly that "children need their mum" and that departments should work harder for reunification.

Geographic Focus: South Australia only - all legal analysis is based on SA-specific child protection legislation, procedural requirements, and parental rights.

User Preferences

Preferred communication style: Simple, everyday language.

System Architecture

Frontend Architecture

Technology Stack:

• React 18 with TypeScript for type-safe component development
• Vite as the build tool and development server
• Wouter for lightweight client-side routing
• TanStack Query v5 for server state management and caching

UI Framework:

• shadcn/ui component library (New York style variant) built on Radix UI primitives
• Tailwind CSS for utility-first styling with custom design tokens
• Typography system based on Inter font family for professional legal credibility
• Comprehensive dark mode support with CSS variables

State Management Strategy:

• Server state managed through React Query with infinite stale time
• Local UI state handled with React hooks
• Form state managed via React Hook Form with Zod validation
• No global client state management needed due to server-centric architecture

Key Design Decisions:

• Component-driven architecture with reusable UI primitives
• Mobile-first responsive design with breakpoint at 768px
• Accessibility-first approach using Radix UI's ARIA-compliant components
• Design system emphasizes reduced cognitive load for stressed users

Backend Architecture

Server Framework:

• Express.js running on Node.js with TypeScript
• ESM module system throughout the codebase
• Custom request logging middleware for API monitoring

Database Layer:

• Drizzle ORM for type-safe database operations
• PostgreSQL via Neon serverless driver with WebSocket support
• Schema-first approach with Zod validation schemas generated from Drizzle schema
• Three core tables: cases, documents, analyses

API Design:

• RESTful endpoints following resource-based URL structure
• File upload handling via Multer with 10MB limit
• Validation using Zod schemas with user-friendly error messages
• Separation of concerns: routes → services → storage layer

Service Architecture:

• DocumentParser Service: Handles PDF and Word document text extraction using pdf-parse and mammoth
• AIAnalysis Service: Orchestrates OpenAI API calls for legal document analysis with specialized prompts emphasizing family preservation
• ObjectStorage Service: Manages file uploads to Replit Object Storage
• Storage Service: Database abstraction layer implementing IStorage interface

Key Architectural Decisions:

• Service layer pattern isolates business logic from route handlers
• Interface-based storage design allows for future storage implementations
• Multer configured for memory storage to work with object storage flow
• File type validation at multiple levels (Multer filter + schema validation)

Data Storage Solutions

Primary Database (PostgreSQL):

• Cases Table: Stores case metadata (child name, state, case number, status)
• Documents Table: Tracks uploaded files with analysis status and object storage URLs
• Analyses Table: Stores AI-generated analysis results with structured JSONB fields for violations and recommendations

Schema Design Rationale:

• UUID primary keys for distributed system compatibility
• JSONB fields for flexible, queryable nested data structures (violations, recommendations)
• Foreign key relationships maintain referential integrity (documentId → documents, caseId → cases)
• Timestamp fields use automatic defaultNow() for audit trail
• Status fields use text enums for flexibility over rigid constraints

Object Storage:

• Replit Object Storage for uploaded document files
• Files stored with secure URLs returned to client
• Separation of file storage from metadata enables scalability

Migration Strategy:

• Drizzle Kit manages schema migrations in /migrations directory
• db:push command for development schema synchronization

Authentication and Authorization

Current State: No authentication implemented

• Application assumes single-user or trusted environment usage
• Session management dependencies present but not actively used (connect-pg-simple)

Future Considerations:

• Express session infrastructure ready for implementation
• Database schema could be extended with user/parent tables
• Multi-tenancy would require user_id foreign keys on cases table

External Dependencies

AI Services:

• OpenAI GPT-5 (latest model as of August 2025) via Replit AI Integrations
• No API key management required—billed to Replit credits
• Specialized system prompts emphasizing family advocacy and rights protection
• Structured output parsing for violations (type, severity, description, legal citations)

File Processing:

• pdf-parse: PDF text extraction for legal documents
• mammoth: Microsoft Word (.docx, .doc) text extraction
• File type restrictions: PDF and Word documents only (validated at upload)

Storage Infrastructure:

• Replit Object Storage: Cloud file storage accessed via Google Cloud Storage SDK
• External account authentication using Replit sidecar service
• Private bucket configuration via PRIVATE_OBJECT_DIR environment variable

Development Tools:

• Replit Dev Tools: Cartographer plugin for code navigation, dev banner
• Vite Plugins: Runtime error overlay for development experience
• Hot Module Replacement (HMR) for rapid development iteration

Database Infrastructure:

• Neon Serverless PostgreSQL: Requires DATABASE_URL environment variable
• WebSocket support for serverless PostgreSQL connections
• Connection pooling via @neondatabase/serverless Pool

Required Environment Variables:

• DATABASE_URL: PostgreSQL connection string (required, throws if missing)
• PRIVATE_OBJECT_DIR: Object storage bucket path (required for uploads)
• AI_INTEGRATIONS_OPENAI_BASE_URL: Replit AI proxy endpoint
• AI_INTEGRATIONS_OPENAI_API_KEY: Replit-managed API credential
• NODE_ENV: Environment indicator (development/production)

Third-Party UI Libraries:

• Radix UI component primitives (20+ packages) for accessible interactions
• Lucide React for consistent iconography
• React Day Picker for calendar/date selection
• Embla Carousel for content carousels
• Recharts for potential data visualization