A preserved governance-first social-services search project; its actionable public directory is retired.
Large-scale scraping of municipal data produces noise, not value. CareConnect takes a different path: manual curation over automated extraction.
The governed inventory contains 204 manually curated records. Public search applies publication, deletion, verification-level, and 180-day freshness rules before displaying a record, so inventory size is not the same as the currently visible service count. Every visible entry must be:
- Published and active — Published and not marked deleted.
- Verification-eligible — Assigned an L1-L3 verification level.
- Within the visibility window — Not older than the 180-day freshness cutoff.
Manual curation remains the data-governance model. The software can display evidence-backed safety and identity tags when a record contains them; those tags are an optional capability, not a universal property of visible records.
Current disposition: controlled retirement of the public directory was deployed and verified on 2026-08-15. The public frontend now exposes a localized non-service retirement surface; the governed corpus, Supabase resources, workflows, and shared keepalive were left unchanged.
CareConnect no longer exposes an actionable public directory. No pilot, partner outreach, corpus restoration, coverage expansion, or research conversion is active. The repository continues to preserve the privacy, accessibility, governance, and offline-search implementation as a technical artifact.
See the current roadmap, public-service retirement disposition, and transition/rollback packet. CareConnect is not a clinical decision support system, emergency service, or official government or 211 service.
This repository contains public project documentation and reproducible development information. Deployment details, credentials, monitoring configuration, private operational notes, exact production paths, and shared-host inventory are intentionally excluded from public documentation.
Shared-host documentation ownership, private project notes, production deployment details, and environment-specific operations are maintained outside this public repository in the private/shared operations source of truth.
Push notifications and external integrations are optional and disabled unless explicitly configured by a maintainer.
- Operational Instrumentation: Aggregate system-health metrics for maintainers.
- Alert-Ready Architecture: Optional alerting hooks for critical service degradation.
- SLO Tracking: Provisional service objectives for uptime and latency review.
- Observability Dashboard: Admin-only system health views for authorized maintainers.
- Circuit Breaker Telemetry: API route coverage for database degradation and recovery signals.
- Tiered Circuit Breaker Protection: Authorization checks wrap database calls to prevent cascading failures.
- Fail-Secure Mutations: High-risk actions (edit/delete) fail closed during database outages to maintain security.
- Safe Read fallbacks: Low-risk permission checks fail open with safe defaults to maintain UI stability.
- Resilience Audit: Full coverage for all authorization assertions with dedicated unit test suite.
- Performance Tracking: Real-time metrics with p50/p95/p99 latency tracking
- Circuit Breaker Pattern: Automatic failover when database unavailable (fast-fail in <1ms)
- Health Check API: Public basic status plus admin-only detailed checks in production
- Load Testing: k6 infrastructure for baseline metrics and regression detection
- Metrics Endpoint: Development-only API for operational visibility
- Organization Management: Create orgs, manage members with role-based access
- Service CRUD: Partners can create, edit, and publish their listings
- Analytics: View aggregate search analytics and user feedback
- Notifications: Partner communication center
- RBAC System: 4 role tiers (Owner, Admin, Editor, Viewer) with 19 granular permissions
- WCAG 2.1 AA-Oriented: High-contrast mode, skip-links, and keyboard navigation, with automated accessibility checks.
- Comprehensive Testing: Automated accessibility audits with Axe-core
- Voice Input: Natural language voice search support
- 7 Languages: English, Canadian French, Arabic, Simplified Chinese, Spanish, Punjabi, Portuguese
- RTL Support: Full right-to-left layout for Arabic interface
- Locale-Aware Search: Language-specific synonyms and results
- Row-Level Security: Database-enforced access controls
- RBAC System: Comprehensive permission matrix
- Session Management: Secure authentication with Supabase
- Audit Trails: Detailed logging of user actions
- Privacy-Conscious Legal Surfaces: Terms of Service and Privacy Policy designed with Canadian privacy principles and PIPEDA/PHIPA considerations in mind. This project is not a formal legal compliance determination.
- Emergency Safeguards: Prominent disclaimers and immediate 911/988 access on crisis pages.
- AI Transparency: Detailed disclaimers for browser-based AI features.
- Accessibility Planning: Dedicated Accessibility Policy and multi-year improvement plan.
- Governance Audit: Public-facing Content Moderation Policy and Feedback Process.
- Entity Preparedness: Documented research for Non-Profit incorporation and liability insurance.
- Synonym Expansion: "Hungry" returns food banks; "rent" surfaces eviction prevention resources.
- Open Now Filter: Real-time availability based on structured operating hours, aligned across local and server search.
- Privacy-First Analytics: Tracks aggregate locale/result-count patterns without logging queries or filter details.
- Crisis Detection: Automatically boosts emergency services when high-risk language is detected.
- Search Explainability: Public result cards and linked detail pages can show deduplicated match reasons for why a service ranked.
- Stale-Data Governance: Records beyond the 180-day freshness window are hidden from search instead of lingering with only a soft score penalty.
- Map Integration: External map previews stay off by default; users can explicitly open directions or load a map preview on service detail pages.
- On-Device Smart Search: Uses a small local LLM (WebLLM + WebGPU) to rewrite/expand natural-language queries for better matching.
- Deterministic Results: The UI renders verified service links from the local directory (no free-form “chatbot answers” shown to users).
- Zero-Knowledge Architecture: Queries never leave the device.
- Offline-Friendly: The service directory and embeddings can be cached for offline search.
- Measurable Impact (v14.0): Public dashboard showing aggregate outcomes and data quality metrics without tracking users.
- Server-Side Search API: Privacy-focused, rate-limited POST endpoint for enhanced security.
- Zero-Logging: Query-, location-, and open-now-driven search responses are
no-storeand never logged to the database. Anonymous category-only browse responses may use short public edge caching. - Shared Ranking Logic: Local and server search now use the same in-memory ranking pipeline for authority, freshness, completeness, intent, proximity, and crisis handling.
- Dynamic Bundle: Falls back to lightweight server queries, saving ~300KB on initial load.
- Place-Aware Filtering — The software supports place-aware coverage metadata and filtering. Current public visibility is determined by publication, deletion, verification-level, and freshness rules; no regional expansion is active.
- Semantic and Fuzzy Search — Natural language queries ("I feel unsafe") and typo correction ("fod" → "food").
- Privacy by Design — No tracking cookies and no search logging. Only functional first-party cookies are used when needed for locale, auth, or short-lived share-target handoff. All inference runs in-browser or anonymously.
- Service Detail Pages — Rich metadata, contact information, and localized content for each listing.
- Partner Claiming Workflow — Organizations can claim, verify, and maintain their own listings.
- Progressive Web App — Installable, works offline.
- WCAG 2.1 AA-Oriented — High-contrast, skip-links, keyboard navigation, and automated checks.
- Community Governance — Residents can flag inaccurate data directly.
- Performance-Oriented — Designed for fast local search and low-bandwidth use, with regression checks for bundle size and load behavior.
- Structured Observability — High-context logging system with timers for performance monitoring.
- Multi-Lingual Support — Full support for 7 languages: English, Canadian French, Arabic, Simplified Chinese, Spanish, Punjabi, and Portuguese.
- Indigenous Health Services — Dedicated filters and culturally safe tags.
- Place-Specific Public Copy — Local acknowledgments and place language are published only when verified for that place.
- Provincial Crisis Lines — 16 Ontario-wide crisis services (988, ConnexOntario, Kids Help Phone, etc.).
- Printable Resource Cards — High-contrast, one-page summaries for any service, designed for offline distribution with locally generated inline QR codes.
- Trust Signals — Visible freshness badges, provenance data, and explicit stale-record warnings for direct links beyond the governance freshness window.
- Public-Safe Provenance — Public API and
services_publicresponses keep provenance fields but replace UUID-shaped verifier identifiers withCareConnect Admin; underlying service provenance remains unchanged for authenticated ownership and audit workflows.
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router) |
| Language | TypeScript |
| Styling | Tailwind CSS v4 |
| UI Components | Radix UI |
| AI / Embeddings | @huggingface/transformers |
| Testing | Vitest · Playwright |
| Database | Supabase (PostgreSQL + pgvector) |
- Node.js 22+
- npm 10+
git clone https://github.com/jerdaw/careconnect.git
cd careconnect
npm install # Installs dependencies and automatically sets up Git hooks
npm run devOpen http://localhost:3000 to view the application.
Note
Git hooks are managed by Husky and automatically configured during npm install via the prepare script. Hooks enforce code quality checks (linting, type-checking, i18n validation) before commits.
| Command | Description |
|---|---|
npm run dev |
Start development server (Turbo) |
npm run build |
Build for production |
npm run generate-embeddings |
Regenerate local embeddings without a full build |
npm run start |
Start production server |
npm test |
Run the default Vitest suite |
npm run test:db |
Run real DB integration tests locally (Docker + psql) |
npm run db:types |
Generate Supabase TS types from a local ephemeral stack |
npm run test:watch |
Vitest in watch mode |
npm run test:coverage |
Generate coverage report |
npm run test:e2e |
Run E2E tests (all browsers) |
npm run test:e2e:local |
Run E2E tests (Chromium only) |
npm run test:a11y |
Run accessibility audit (Axe-core) |
npm run type-check |
TypeScript compiler check |
npm run lint |
ESLint code quality check |
npm run lint:fix |
ESLint with auto-fix |
npm run format |
Format code with Prettier |
npm run format:check |
Check code formatting |
npm run ci:check |
Run CI validation checks (DB lane auto-skips locally if prerequisites are missing) |
npm run check:refs |
Validate repo-local docs/script/path references |
npm run check:root |
Check project root hygiene |
Public documentation does not include production host paths or release commands. Maintainers should use the private deployment notes and shared operations inventory for live releases.
| Command | Description |
|---|---|
npm run test:load |
Run search API load test (realistic) |
npm run test:load:smoke |
Run smoke test (basic connectivity) |
npm run test:load:sustained |
Run sustained load test (30min) |
npm run test:load:spike |
Run spike test (sudden traffic spike) |
These commands require k6 to be installed locally and available on your PATH. The repo does not vendor the binary.
| Command | Description |
|---|---|
npm run validate-data |
Validate data schema (Zod) |
npm run db:validate |
Alias for validate-data |
npm run db:verify |
Verify database integrity (row count, RLS) |
npm run check:embeddings |
Validate local service IDs and embedding vector shape without regenerating files |
npm run health-check |
Validate all service URLs |
npm run phone-validate |
Validate phone numbers (Twilio) |
npm run check-staleness |
Check for stale/unverified data; add -- --as-of YYYY-MM-DD --out-dir <dir> to export a dated JSON/Markdown/CSV queue |
npm run audit:data |
Comprehensive data completeness audit |
npm run audit:qa |
Data quality and integrity audit |
npm run audit:coords |
Export services with missing coordinates |
npm run audit:hours |
Export services with missing operating hours |
npm run audit:access-scripts |
Audit access_script quality |
npm run audit:l3 |
Export L3 verification candidates |
npm run bilingual-check |
Check bilingual content coverage |
npm run i18n-audit |
Audit i18n translation key coverage |
npm run analyze |
Analyze production bundle size |
| Command | Description |
|---|---|
npm run tools:search "food bank" |
Run the local CLI search tool |
npm run search:qa |
Run curated local search QA scenarios |
npm run verify:search-ranking |
Verify API ranking against a running local app |
npm run verify:rls |
Check public/private Supabase access boundaries |
npm run audit:pilot-readiness -- --scope-file <path> |
Historical v22 pilot-readiness artifact exporter |
npm run check:v22-evidence |
Historical v22 C1/D4 evidence consistency validator |
npm run check:v22-threat-model |
Historical v22 threat-model consistency validator |
npm run check:v22-gate0 |
Historical v22 Gate 0 document validator |
npm run normalize:services -- --dry-run |
Preview legacy schema normalization without writing data |
npm run ingest:import-response -- --help |
Show draft-import CLI usage |
The v22 commands remain available to validate preserved historical artifacts. They do not enforce the current retirement disposition or authorize pilot execution.
npm run db:types requires a Docker-capable local environment because it boots the minimal local Supabase profile before generating types/supabase.ts.
| Command | Description |
|---|---|
npm run export:access-script-fr |
Export access_script fields for French |
npm run translate:prompt |
Generate AI translation prompts |
npm run translate:parse |
Parse AI response into structured JSON |
npm run translate:validate |
Validate translation batch |
npm run backfill:hours-text |
Backfill hours_text from structured hours |
npm run backfill:db-runtime-fields |
Fill missing DB runtime fields from curated JSON |
npm run geocode |
Geocode addresses (requires OPENCAGE_API_KEY) |
See French Translation Workflow for detailed translation process.
Copy .env.example to .env.local. Core search functionality works without API keys; database features require Supabase credentials.
For Librarian Model (Server-Side Search):
NEXT_PUBLIC_SEARCH_MODE=server(Defaults to local if unset).
Optional configuration:
APP_VERSIONsets the server-side version string returned by health endpoints.OPENAI_API_KEY,GOOGLE_AI_API_KEY, andOPENCAGE_API_KEYsupport maintainer-only enrichment workflows.UPSTASH_REDIS_REST_URLandUPSTASH_REDIS_REST_TOKENenable distributed rate limiting; leave them unset to use the in-memory fallback.ALLOW_211_SYNC=1andAPI_211_KEYare required together for an explicitly approved manual 211 sync. Leave both unset for normal development.npm run validate:envchecks.env.local; local placeholder values intentionally fail that production-readiness check.
To enable the Partner Portal, authentication, and analytics:
-
Create a project at database.new.
-
Add your credentials to
.env.local:NEXT_PUBLIC_SUPABASE_URL=https://example.supabase.co NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=example-publishable-key SUPABASE_SECRET_KEY=
-
Apply the schema via Supabase CLI migrations:
npx supabase link --project-ref your-project-ref npx supabase db push
-
Migrate local data:
npx tsx scripts/migrate-data.ts
-
For existing Supabase environments that previously relied on the old DB-plus-JSON runtime overlay, run the rollout-safe DB backfill once:
npm run backfill:db-runtime-fields
This fills missing DB-authoritative runtime fields such as
synthetic_queries,coordinates,hours_text, andaccess_scriptfrom the curated snapshot without overwriting non-empty live values. -
For authenticated uptime probes, set:
HEALTH_PROBE_TOKEN=
GET /api/v1/healthremains a public, read-only status endpoint.GET /api/v1/health/probeis the authenticated probe path that records uptime samples and evaluates alerting.
This project is community-led. Safety and accuracy take precedence over volume.
- Roadmap
- Public-service retirement disposition
- Documentation Guidelines
- Testing Standards
- Multi-Lingual Development Guide
- Acknowledgments & Governance
New service intake remains inactive after public-directory retirement. The criteria below are preserved as conditional history; they are not an invitation to submit records and do not authorize ingestion.
- Serves a supported CareConnect place, or is clearly available province-wide or Canada-wide.
- Has a verifiable phone number or physical address.
- Free or subsidized.
MIT License