228 lines
9.3 KiB
Markdown
228 lines
9.3 KiB
Markdown
# Synculous
|
|
|
|
A routine and medication management app designed as a prosthetic for executive function. Built for people with ADHD.
|
|
|
|
The app externalizes the things ADHD impairs — time awareness, sequence memory, task initiation, and emotional regulation around failure — into a guided, sequential interface with immediate feedback and zero shame.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
synculous/
|
|
├── synculous-client/ # Next.js 16 frontend (React, Tailwind)
|
|
├── api/ # Flask REST API
|
|
│ ├── main.py # App entry point, auth routes
|
|
│ └── routes/ # Domain route modules
|
|
│ ├── routines.py # Routines CRUD + sessions
|
|
│ ├── routine_sessions_extended.py # Pause, resume, abort, notes
|
|
│ ├── routine_stats.py # Completion stats, streaks, weekly summary
|
|
│ ├── routine_templates.py # Premade routine templates
|
|
│ ├── routine_steps_extended.py # Step instructions, types, media
|
|
│ ├── routine_tags.py # Tagging system
|
|
│ ├── medications.py # Medication scheduling + adherence
|
|
│ ├── preferences.py # User settings + timezone
|
|
│ ├── notifications.py # Web push subscriptions
|
|
│ ├── rewards.py # Variable reward system
|
|
│ └── victories.py # Achievement detection
|
|
├── core/ # Shared business logic
|
|
│ ├── postgres.py # Generic PostgreSQL CRUD
|
|
│ ├── auth.py # JWT + bcrypt authentication
|
|
│ ├── users.py # User management
|
|
│ ├── routines.py # Routine/session/streak logic
|
|
│ ├── tz.py # Timezone-aware date/time helpers
|
|
│ └── notifications.py # Multi-channel notifications
|
|
├── scheduler/
|
|
│ └── daemon.py # Background polling for reminders
|
|
├── bot/ # Discord bot (optional)
|
|
├── ai/ # LLM parser for natural language commands
|
|
├── config/
|
|
│ ├── schema.sql # Database schema
|
|
│ ├── seed_templates.sql # 12 premade ADHD-designed routine templates
|
|
│ ├── seed_rewards.sql # Variable reward pool
|
|
│ └── .env.example # Environment template
|
|
├── docker-compose.yml
|
|
└── Dockerfile
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Copy environment config
|
|
cp config/.env.example config/.env
|
|
|
|
# Edit with your values
|
|
nano config/.env
|
|
|
|
# Start everything
|
|
docker-compose up
|
|
```
|
|
|
|
This starts five services:
|
|
|
|
| Service | Port | Description |
|
|
|---------|------|-------------|
|
|
| `db` | 5432 | PostgreSQL 16 with schema + seed data |
|
|
| `app` | 8080 | Flask API |
|
|
| `scheduler` | — | Background daemon for medication/routine reminders |
|
|
| `bot` | — | Discord bot (optional, needs `DISCORD_BOT_TOKEN`) |
|
|
| `client` | 3000 | Next.js frontend |
|
|
|
|
## Features
|
|
|
|
### Routines
|
|
- Create routines with ordered steps (4-7 steps recommended)
|
|
- Run sessions with a guided, one-step-at-a-time focus interface
|
|
- Complete, skip, pause, resume, or cancel sessions
|
|
- Swipe gestures for step completion on mobile
|
|
- Per-step timing with visual countdown
|
|
- Animated celebration screen on completion with streak stats and variable rewards
|
|
|
|
### Premade Templates
|
|
12 ADHD-designed templates ship out of the box, seeded from `config/seed_templates.sql`:
|
|
|
|
| Template | What it's for |
|
|
|----------|---------------|
|
|
| Morning Launch | Getting from bed to ready. First step: just sit up. |
|
|
| Leaving the House | The keys-wallet-phone checklist. |
|
|
| Focus Sprint | One focused work block with environment setup first. |
|
|
| Wind Down | Screen-first sleep transition. |
|
|
| Quick Tidy | Fast sweep, not deep cleaning. Completable on bad days. |
|
|
| Body Reset | Minimum viable hygiene. Zero judgment. |
|
|
| Unstuck | For executive function paralysis. Pure two-minute-rule. |
|
|
| Evening Reset | Set tomorrow up to be easier. |
|
|
| Move Your Body | Not a workout. Just movement. Starts with shoes. |
|
|
| Sunday Reset | Weekly prep so Monday doesn't ambush you. |
|
|
| Cook a Meal | One meal, start to finish, low activation energy. |
|
|
| Errand Run | Externalized planning + sequencing for errands. |
|
|
|
|
All templates follow the design framework: two-minute-rule entry points, concrete instructions, zero-shame language, 4-6 steps max.
|
|
|
|
### Medications
|
|
- Scheduling: daily, twice daily, specific days, every N days, as-needed (PRN)
|
|
- "Today's meds" view with cross-midnight lookahead (late night + early morning)
|
|
- Take, skip, snooze actions with logging
|
|
- Adherence tracking and statistics
|
|
- Refill tracking with low-quantity alerts
|
|
- Background reminders via the scheduler daemon
|
|
|
|
### Streaks and Stats
|
|
- Per-routine streak tracking (current + longest)
|
|
- Weekly summary across all routines
|
|
- Completion rate and average duration stats
|
|
- Victory detection (comebacks, weekend completions, variety, consistency)
|
|
- Milestone celebrations at 3, 7, 14, 21, 30, 60, 90, 100, 365 days
|
|
|
|
### Rewards
|
|
- Variable reward pool seeded from `config/seed_rewards.sql`
|
|
- Random reward on routine completion (post-completion only, never mid-routine)
|
|
- Reward history tracking per user
|
|
- Common and rare rarity tiers
|
|
|
|
### Notifications
|
|
- Web push notifications via VAPID
|
|
- Discord webhooks
|
|
- ntfy support
|
|
- Scheduled reminders for medications and routines
|
|
|
|
### Timezone Support
|
|
All date/time operations respect the user's local timezone:
|
|
- The frontend sends `X-Timezone-Offset` with every API request
|
|
- The timezone offset is also persisted to `user_preferences` for background jobs
|
|
- Streaks, "today's meds," weekly stats, and reminders all use the user's local date
|
|
- The scheduler daemon looks up each user's stored offset for reminder timing
|
|
|
|
### User Preferences
|
|
- Sound effects (default off — habituation risk)
|
|
- Haptic feedback (default on)
|
|
- Launch screen toggle
|
|
- Celebration style
|
|
- Timezone offset (auto-synced from browser)
|
|
|
|
## API Overview
|
|
|
|
All endpoints require `Authorization: Bearer <token>` except `/api/register` and `/api/login`.
|
|
|
|
### Auth
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| POST | `/api/register` | Create account |
|
|
| POST | `/api/login` | Get JWT token |
|
|
|
|
### Routines
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/routines` | List user's routines |
|
|
| POST | `/api/routines` | Create a routine |
|
|
| GET | `/api/routines/:id` | Get routine with steps |
|
|
| PUT | `/api/routines/:id` | Update routine |
|
|
| DELETE | `/api/routines/:id` | Delete routine |
|
|
| GET | `/api/routines/:id/steps` | List steps |
|
|
| POST | `/api/routines/:id/steps` | Add a step |
|
|
| PUT | `/api/routines/:id/steps/reorder` | Reorder steps |
|
|
| POST | `/api/routines/:id/start` | Start a session |
|
|
|
|
### Sessions
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/sessions/active` | Get active or paused session |
|
|
| POST | `/api/sessions/:id/complete-step` | Complete current step |
|
|
| POST | `/api/sessions/:id/skip-step` | Skip current step |
|
|
| POST | `/api/sessions/:id/pause` | Pause session |
|
|
| POST | `/api/sessions/:id/resume` | Resume session |
|
|
| POST | `/api/sessions/:id/cancel` | Cancel session |
|
|
| POST | `/api/sessions/:id/abort` | Abort with reason |
|
|
|
|
### Medications
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/medications` | List medications |
|
|
| POST | `/api/medications` | Add medication |
|
|
| GET | `/api/medications/today` | Today's schedule with status |
|
|
| POST | `/api/medications/:id/take` | Log dose taken |
|
|
| POST | `/api/medications/:id/skip` | Log dose skipped |
|
|
| GET | `/api/medications/adherence` | Adherence stats |
|
|
| GET | `/api/medications/refills-due` | Refills due soon |
|
|
|
|
### Stats
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/routines/:id/stats` | Routine completion stats |
|
|
| GET | `/api/routines/:id/streak` | Routine streak |
|
|
| GET | `/api/routines/streaks` | All streaks |
|
|
| GET | `/api/routines/weekly-summary` | Weekly progress |
|
|
| GET | `/api/victories` | Achievement detection |
|
|
|
|
### Templates, Tags, Rewards, Preferences
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/templates` | List available templates |
|
|
| POST | `/api/templates/:id/clone` | Clone template to user's routines |
|
|
| GET/PUT | `/api/preferences` | User settings |
|
|
| GET | `/api/rewards/random` | Random completion reward |
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `DB_HOST` | PostgreSQL host |
|
|
| `DB_PORT` | PostgreSQL port |
|
|
| `DB_NAME` | Database name |
|
|
| `DB_USER` | Database user |
|
|
| `DB_PASS` | Database password |
|
|
| `JWT_SECRET` | JWT signing secret |
|
|
| `DISCORD_BOT_TOKEN` | Discord bot token (optional) |
|
|
| `API_URL` | API URL for bot (default: `http://app:5000`) |
|
|
| `OPENROUTER_API_KEY` | OpenRouter API key (for AI parser) |
|
|
| `POLL_INTERVAL` | Scheduler poll interval in seconds (default: 60) |
|
|
|
|
## Design Framework
|
|
|
|
Synculous follows a documented design framework based on research from 9 books on behavior design, cognitive psychology, and ADHD. The three core principles:
|
|
|
|
1. **Immediate Feedback** — Visual state change on tap in <0.1s. Per-step completion signals. Post-routine celebration.
|
|
2. **One Thing at a Time** — Current step visually dominant. No decisions during execution. 4-7 steps max per routine.
|
|
3. **Zero Shame** — No failure language. Streaks as identity markers, not performance metrics. Non-punitive everywhere.
|
|
|
|
## License
|
|
|
|
MIT
|