Skip to content

Commit b979c96

Browse files
Sonra0Sonra0
committed
docs: add hackathon README with Google/ElevenLabs integration details
1 parent 27a4d72 commit b979c96

1 file changed

Lines changed: 225 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 225 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,225 @@
1-
# Seniora-AI
1+
<p align="center">
2+
<img src="public/logo.png" alt="Seniora Logo" width="180" />
3+
</p>
4+
5+
<h1 align="center">Seniora.life</h1>
6+
<h3 align="center">Compassionate Care & Support — Powered by AI</h3>
7+
8+
<p align="center">
9+
<b>Hack Canada 2026</b> &middot; Built in 36 hours (+ 30-day build period) at Waterloo's SPUR Innovation Centre
10+
</p>
11+
12+
<p align="center">
13+
<img src="https://img.shields.io/badge/Google-Gemini%20API-4285F4?style=for-the-badge&logo=google&logoColor=white" />
14+
<img src="https://img.shields.io/badge/Google-Antigravity-34A853?style=for-the-badge&logo=google&logoColor=white" />
15+
<img src="https://img.shields.io/badge/Google-Firebase-FFCA28?style=for-the-badge&logo=firebase&logoColor=black" />
16+
<img src="https://img.shields.io/badge/Google-Cloud-4285F4?style=for-the-badge&logo=googlecloud&logoColor=white" />
17+
<img src="https://img.shields.io/badge/Gemini-CLI-8E75B2?style=for-the-badge&logo=google&logoColor=white" />
18+
<img src="https://img.shields.io/badge/ElevenLabs-Voice%20AI-000000?style=for-the-badge" />
19+
<img src="https://img.shields.io/badge/Vultr-Cloud%20VPS-007BFC?style=for-the-badge&logo=vultr&logoColor=white" />
20+
</p>
21+
22+
---
23+
24+
## The Problem
25+
26+
**6.5 million Canadians** are family caregivers. Many live far from the elderly relatives they care for, and the constant worry about whether they took their medication, how they're feeling, or whether their cognitive health is declining is exhausting.
27+
28+
Existing solutions are either too clinical (and ignored), too expensive, or require the elderly person to use apps and devices they can't navigate.
29+
30+
**What if care could just... call?**
31+
32+
---
33+
34+
## What Seniora Does
35+
36+
Seniora is an AI-powered elderly care platform that makes **automated, natural-sounding phone calls** to elderly individuals — no app downloads, no smart devices, no learning curve. Just a phone that rings.
37+
38+
### Daily Medication Reminders
39+
Seniora calls your loved one at the scheduled time with a warm, conversational reminder about each medication — dosage, instructions, and all. If they don't pick up, it retries intelligently.
40+
41+
### Cognitive Assessments
42+
Daily voice-based cognitive check-ins with personalized questions (people recognition, orientation, personal memory, general knowledge). The AI evaluates answers in real-time, scores the session, and tracks trends over 30 days with beautiful analytics dashboards.
43+
44+
### Emotional Check-ins
45+
After cognitive questions, Seniora asks how the person is feeling. If the AI detects distress, it immediately alerts caregivers via Telegram and offers to connect the elder with their emergency contact — right from the call.
46+
47+
### Vocal Analysis
48+
Every call is analyzed for vocal biomarkers that may indicate early signs of depression, Parkinson's, or changes in overall wellness. Results appear in the caregiver dashboard as radar charts and trend graphs.
49+
50+
### Caregiver Network
51+
Multiple caregivers can monitor the same person. Instant Telegram notifications with detailed assessment reports, emergency alerts, and call summaries keep everyone in the loop.
52+
53+
---
54+
55+
## Built Heavily with Google & ElevenLabs
56+
57+
This project is **deeply integrated with the Google ecosystem and ElevenLabs** voice technology. They aren't just tools we used — they're the backbone of the entire platform.
58+
59+
### Google Ecosystem
60+
61+
| Product | How We Use It |
62+
|---------|--------------|
63+
| **Gemini API** (gemini-2.5-flash) | The brain of every phone call. Generates personalized greeting scripts, evaluates cognitive assessment answers in real-time, scores emotional responses (positive/negative sentiment), produces warm answer reviews, and creates AI summaries of each session. Every single AI interaction is powered by Gemini. |
64+
| **Google Antigravity** | Our primary development environment. The entire codebase — frontend, backend, API routes, database schema, call flow logic — was built inside Antigravity with its agentic AI assistance, tab autocompletion, and context-aware coding. |
65+
| **Gemini CLI** | Used throughout development for rapid prototyping, debugging complex Twilio webhook flows, and generating boilerplate code for new features. |
66+
| **Firebase Auth** | All user authentication — Google OAuth sign-in, email/password registration, session management, and ID token verification for API routes. |
67+
| **Google Cloud** | Infrastructure foundation. Database hosting, environment management, and the deployment pipeline that keeps everything running. |
68+
69+
### ElevenLabs
70+
71+
| Feature | How We Use It |
72+
|---------|--------------|
73+
| **Text-to-Speech** | Every phone call uses ElevenLabs to generate natural, human-sounding audio. Greetings, questions, emotional responses, answer reviews — all synthesized in real-time with ElevenLabs voices so the calls feel like talking to a real person, not a robot. |
74+
| **Voice Cloning** | Caregivers can clone a familiar voice (like a family member) so the elderly person hears someone they recognize on the phone. This dramatically increases engagement and trust. |
75+
| **Multi-language Support** | Calls are generated in the elder's preferred language (English, Arabic, and more) with natural pronunciation and cadence. |
76+
| **Non-fatal TTS Pipeline** | We built a resilient audio pipeline where every ElevenLabs call is wrapped in try/catch — if the API is rate-limited or down, the system gracefully falls back to Twilio's built-in `<Say>` tags so calls **always** go through. |
77+
78+
---
79+
80+
## Tech Stack
81+
82+
| Layer | Technology |
83+
|-------|-----------|
84+
| **Framework** | Next.js 16 (App Router), React 19, TypeScript |
85+
| **Styling** | Tailwind CSS 4, Framer Motion (page transitions, stagger animations) |
86+
| **Charts** | nivo (D3-based) — RadialBar, Line, Radar, HeatMap for medical analytics |
87+
| **Database** | PostgreSQL + Prisma ORM 7 |
88+
| **Auth** | Firebase Auth (Google OAuth + Email/Password) |
89+
| **AI** | Google Gemini API (gemini-2.5-flash) |
90+
| **Voice** | ElevenLabs TTS + Voice Cloning |
91+
| **Telephony** | Twilio (outbound calls, speech recognition, call recording) |
92+
| **Notifications** | Telegram Bot API (caregiver alerts + assessment reports) |
93+
| **Deployment** | Vultr VPS, PM2 process manager, auto-deploy via GitHub |
94+
| **Dev Tools** | Google Antigravity, Gemini CLI, Claude Code |
95+
96+
---
97+
98+
## Architecture
99+
100+
```
101+
┌─────────────────────────────────────────────────────────┐
102+
│ Next.js App Router │
103+
│ ┌──────────┐ ┌──────────┐ ┌────────────────────────┐ │
104+
│ │ Landing │ │Dashboard │ │ Assessment Analytics │ │
105+
│ │ Page │ │ + Sidebar│ │ (Dark Theme + Charts) │ │
106+
│ └──────────┘ └──────────┘ └────────────────────────┘ │
107+
├─────────────────────────────────────────────────────────┤
108+
│ API Routes │
109+
│ /api/elderly /api/webhooks/assessment /api/recording │
110+
├─────────────────────────────────────────────────────────┤
111+
│ Services Layer │
112+
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
113+
│ │ Gemini │ │ElevenLabs│ │ Twilio │ │Telegram │ │
114+
│ │ AI │ │ TTS │ │ Calls │ │ Bot │ │
115+
│ └──────────┘ └──────────┘ └──────────┘ └─────────┘ │
116+
├─────────────────────────────────────────────────────────┤
117+
│ PostgreSQL + Prisma │ Firebase Auth │ Cron Worker │
118+
└─────────────────────────────────────────────────────────┘
119+
```
120+
121+
### Call Flow (Assessment)
122+
123+
```
124+
Cron triggers call → Twilio dials elder
125+
→ ElevenLabs generates warm greeting audio
126+
→ Gemini generates personalized questions
127+
→ Elder answers via speech recognition
128+
→ Gemini evaluates each answer in real-time
129+
→ Emotional check-in question
130+
→ Gemini analyzes sentiment
131+
→ If NEGATIVE: Telegram alert + offer emergency call
132+
→ If POSITIVE: warm encouragement
133+
→ Gemini generates answer review summary
134+
→ ElevenLabs synthesizes review audio
135+
→ Session completes → Telegram report to all caregivers
136+
```
137+
138+
---
139+
140+
## Features at a Glance
141+
142+
- **AI Voice Calls** — Natural conversations powered by ElevenLabs + Gemini
143+
- **Smart Medication Reminders** — Scheduled calls with intelligent retry logic
144+
- **Cognitive Assessment** — Daily voice-based check-ins with 30-day trend tracking
145+
- **Emotional Detection** — Real-time sentiment analysis with emergency escalation
146+
- **Medical Analytics Dashboard** — Dark-themed with score gauges, trend lines, radar charts, heatmaps
147+
- **Voice Cloning** — Familiar voices for better engagement
148+
- **Caregiver Network** — Multi-caregiver support with Telegram notifications
149+
- **Subscription Tiers** — Free (1 profile, 2 reminders) and Premium ($10/mo, unlimited)
150+
- **Responsive Design** — Desktop sidebar + mobile bottom navigation
151+
- **Animated UI** — Framer Motion page transitions, stagger effects, tab crossfades
152+
153+
---
154+
155+
## Sponsor Categories
156+
157+
- **Google - Build with AI Track** — Fully built with Google AI tools (Gemini API, Firebase, Google Cloud, Antigravity, Gemini CLI). Solves a real problem for Canadian elderly care.
158+
- **[MLH] Best Use of Gemini API** — Gemini powers every AI interaction: greeting generation, answer evaluation, emotional analysis, session summaries.
159+
- **[MLH] Best Hack Built with Google Antigravity** — Entire codebase developed in Antigravity.
160+
- **MLH x ElevenLabs - Best Project Built with ElevenLabs** — Every call uses ElevenLabs TTS + voice cloning for natural, human-sounding conversations.
161+
- **[MLH] Best Use of Vultr** — Deployed on Vultr Cloud VPS with PM2 process management.
162+
- **Vivirion Solutions - Best Practical Healthcare Hack** — Directly improves elderly healthcare through AI-powered cognitive monitoring and caregiver support.
163+
- **SPUR Founder Track** — Real Canadian healthcare problem with startup potential (seniora.life).
164+
- **Most Technically Complex AI Hack** — Multi-model agentic architecture: Gemini for intelligence, ElevenLabs for voice, Twilio for telephony, real-time vocal biomarker analysis.
165+
166+
---
167+
168+
## Tools, Libraries & Services
169+
170+
**Core:** Next.js 16, React 19, TypeScript, Tailwind CSS 4, PostgreSQL, Prisma 7
171+
172+
**AI & Voice:** Google Gemini API (gemini-2.5-flash), ElevenLabs TTS & Voice Cloning
173+
174+
**Google Products:** Firebase Auth, Google Cloud, Google Antigravity (IDE), Gemini CLI
175+
176+
**Frontend:** Framer Motion, nivo (D3-based charts: RadialBar, Line, Radar, HeatMap)
177+
178+
**Telephony:** Twilio (Voice, Speech Recognition, Call Recording, Verify OTP)
179+
180+
**Notifications:** Telegram Bot API
181+
182+
**Infrastructure:** Vultr Cloud VPS, PM2, GitHub (auto-deploy)
183+
184+
**Dev Tools:** Google Antigravity, Gemini CLI, Claude Code
185+
186+
---
187+
188+
## Running Locally
189+
190+
```bash
191+
# Clone
192+
git clone https://github.com/Sonra0/Seniora-AI.git
193+
cd Seniora-AI
194+
195+
# Install
196+
npm install
197+
npx prisma generate
198+
199+
# Set up environment
200+
cp .env.example .env
201+
# Fill in: DATABASE_URL, Firebase config, Twilio, ElevenLabs, Gemini, Telegram
202+
203+
# Database
204+
npx prisma migrate dev
205+
206+
# Run
207+
npm run dev # Web app on :3000
208+
npm run cron # Background worker for scheduled calls
209+
```
210+
211+
---
212+
213+
## The Team
214+
215+
Built with love at **Hack Canada 2026** by the Seniora team.
216+
217+
Because the people who raised us deserve more than a reminder app — they deserve a voice that cares.
218+
219+
---
220+
221+
<p align="center">
222+
<img src="public/logo.png" alt="Seniora" width="80" />
223+
<br />
224+
<b>seniora.life</b> — Care that calls. Literally.
225+
</p>

0 commit comments

Comments
 (0)