BreatheOS is a breathing and cardiovascular wellness app I built to make breath training feel calm, focused, and a little more personal than a normal timer app.
It combines guided breathing sessions, blood pressure logs, sleep sounds, session history, and a real-time "Breathe Together" room feature.
Built by Godstime Aburu GitHub: BboyGT
I wanted BreatheOS to feel like a quiet space for training your breathing habits, not just another dashboard full of numbers.
The app focuses on:
- Lower blood pressure breathing routines
- Lung capacity training
- Breath-hold practice
- Sleep sounds for winding down
- Tracking progress over time
- Breathing together with someone else in real time
This is not a medical device and it is not medical advice. It is a wellness tool for guided breathing, habit tracking, and relaxation.
The sleep sounds in this project are generated with the Web Audio API. That means the app creates ambient sounds like rain, water, wind, fire, and atmosphere in the browser instead of shipping downloaded audio files.
- Guided breathing sessions with progressive programs
- Training goals for Lower BP, Lung, and Breath Hold
- Blood pressure logging and charts
- Session history calendar
- Streak and completion stats
- Sleep sounds with duration and volume controls
- Crossfading sound engine
- Breathe Together rooms using WebSockets
- Magic-link authentication with NextAuth
- Prisma database support
- Mobile-first layout with desktop support
- PWA-ready structure
- Next.js 16
- React 19
- TypeScript
- Tailwind CSS 4
- Framer Motion
- Prisma
- NextAuth
- Web Audio API
- WebSocket server with
ws - shadcn/Radix UI components
Clone the project:
git clone https://github.com/BboyGT/BreathOS.git
cd BreathOSInstall dependencies:
npm installSet up environment variables:
cp .env.example .env.localUpdate .env.local with your own values.
Example:
DATABASE_URL="file:./db/breatheos.db"
NEXTAUTH_URL="http://localhost:3333"
NEXTAUTH_SECRET="replace-this-with-a-real-secret"
EMAIL_SERVER_HOST="smtp.example.com"
EMAIL_SERVER_PORT="587"
EMAIL_SERVER_USER="your-email-user"
EMAIL_SERVER_PASSWORD="your-email-password"
EMAIL_FROM="BreatheOS <noreply@example.com>"
NEXT_PUBLIC_WS_URL="ws://localhost:4001"Push the Prisma schema:
npm run db:pushRun the app:
npm run devThe app runs at:
http://localhost:3333
The Breathe Together feature needs the WebSocket server.
Run the app and WebSocket server together:
npm run dev:fullOr run them separately:
npm run devnpm run wsDefault WebSocket URL:
ws://localhost:4001
npm run devStarts the Next.js development server on port 3333.
npm run buildBuilds the production version.
npm run startStarts the production server.
npm run db:pushPushes the Prisma schema to the database.
npm run db:generateRegenerates the Prisma client.
npm run wsStarts the WebSocket server for Breathe Together.
BreathOS/
|-- prisma/
| `-- schema.prisma
|-- public/
|-- src/
| |-- app/
| | |-- api/
| | |-- auth/
| | |-- globals.css
| | |-- layout.tsx
| | `-- page.tsx
| |-- components/
| | |-- breatheos/
| | | |-- index.tsx
| | | |-- bp-chart.tsx
| | | `-- nature-sound.ts
| | `-- ui/
| `-- lib/
|-- ws-server.cjs
|-- package.json
`-- README.md
Before deploying:
- Set a real
NEXTAUTH_SECRET - Use production email credentials
- Set
NEXTAUTH_URLto your deployed URL - Use a production database if needed
- Deploy the WebSocket server separately if you want Breathe Together online
- Keep
.envand.env.localout of GitHub
The app currently uses generated sounds, not copied YouTube audio.
If real sound files are added later, they should only come from sources that allow use in projects like this. Add attribution in this README if the license requires it.
Built by Godstime Aburu GitHub: BboyGT
I built this as a personal wellness project around breathing, focus, and cardiovascular habit tracking.