# 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