FirstAid AI

FirstAid AI is a web-based first-aid guidance interface designed to help a bystander stay calm, record what happens, and take structured first steps while seeking trained help. It combines an emergency-session experience, practice scenarios, safety tips, and a factual handover report.

Safety notice: FirstAid AI is an informational demo, not a diagnostic tool, emergency-dispatch system, medical record, or substitute for professional medical advice. In a severe or life-threatening emergency, contact local emergency services immediately.

Live demo and source code

• Live frontend: firstaid-ai-blond.vercel.app
• Repository: github.com/danilao-bot/firstaid

What it does

• Guides users through focused first-aid emergency sessions.
• Provides practice flows and first-aid tips for preparation.
• Records reported answers, actions, user notes, a timeline, and a transcript.
• Flags severe scenarios for emergency-services escalation without claiming that a call or dispatch occurred.
• Generates an editable handover report from recorded session data only, with timestamps and a non-official-record disclaimer.
• Supports live session updates through WebSockets when the local backend is enabled.

Built with Codex and GPT-5.6

FirstAid AI was developed with Codex using GPT-5.6 as a hands-on engineering partner. Codex was used to inspect the existing React application, preserve its user experience, and implement the missing backend without redesigning or breaking the frontend.

Key Codex contributions included:

• Creating the standalone Node.js, Express, and TypeScript backend in backend/.
• Matching the frontend's existing API contracts for classification, triage, summaries, Q&A, practice feedback, and speech-service placeholders.
• Implementing an in-memory emergency-session model and factual handover-report generator.
• Adding a WebSocket server compatible with the frontend emergency-socket message format.
• Adding CORS, environment configuration, backend documentation, build scripts, and endpoint tests.
• Finding and resolving strict TypeScript build issues during verification.
• Organizing frontend/backend setup instructions for contributors and judges.

Codex also helped us make deliberate safety decisions: the first version uses deterministic demo responses, does not require paid AI API keys, does not invent medical facts in reports, and never claims emergency services were called or dispatched.

Technology stack

Frontend

• React 18
• TypeScript
• Vite
• Tailwind CSS
• React Router
• Framer Motion
• Lucide React

Backend

• Node.js
• Express
• TypeScript
• ws for WebSocket communication
• cors for frontend access
• dotenv for environment configuration
• Node's built-in node:test for endpoint tests
• tsx for TypeScript development mode

Platform and storage

• Frontend deployment: Vercel
• Source control: GitHub
• MVP storage: an in-memory JavaScript Map; session data resets when the backend restarts

No OpenAI, Gemini, ElevenLabs, or other paid API key is required for this first demo version. The text-to-speech and speech-to-text routes explicitly return a not_configured response.

Project structure

firstaid-master/
├── src/                 # React + Vite frontend
├── backend/             # Express + TypeScript API and WebSocket server
│   ├── src/
│   ├── test/
│   ├── .env.example
│   └── README.md
├── package.json         # Frontend scripts and dependencies
└── vite.config.ts

Run locally

1. Start the backend

cd backend
npm.cmd install
Copy-Item .env.example .env
npm.cmd run dev

The backend starts at http://localhost:5000. Confirm it is running at http://localhost:5000/health.

2. Configure and start the frontend

In the project root, create a .env file containing:

VITE_USE_LIVE_BACKEND=true
VITE_API_BASE_URL=http://localhost:5000/api

Then run:

npm.cmd install
npm.cmd run dev

Open the Vite URL printed in the terminal, usually http://localhost:5173.

Backend API

The local API is available at http://localhost:5000/api.

• POST /ai/classify
• POST /ai/triage/next
• POST /ai/summarize
• POST /ai/qa
• POST /ai/practice/review
• POST /ai/tts and POST /ai/stt return clear not_configured demo responses
• POST /emergency/start
• POST /emergency/:sessionId/respond
• GET /emergency/:sessionId
• GET /emergency/:sessionId/report
• POST /emergency/:sessionId/end

WebSocket clients connect to:

ws://localhost:5000/ws/session/:sessionId

Verify the backend

cd backend
npm.cmd run build
npm.cmd test

The tests check the health endpoint and verify that a session report contains only recorded data, including the required disclaimer.

Future work

• Deploy the backend publicly and configure the production frontend to use it.
• Replace in-memory storage with a secure persistent database such as Supabase/PostgreSQL.
• Add reviewed authentication and secure report-sharing controls.
• Validate all first-aid content with qualified medical professionals.
• Improve offline, accessibility, and carefully guarded speech-support capabilities.

License

Copyright (c) 2026 FirstAid AI. All Rights Reserved.

See the LICENSE file for full terms. No part of this project may be reproduced, distributed, or modified without prior written permission.