🧭 Compass

A self-hosted compass for your life's voyages

Anchor goals · Plan voyages · Calibrate direction

English · 中文

---

Turn vague "I want to be better" into a voyage you can plot, sail, and log. Compass borrows the metaphor of nautical instruments: anchor goals on a four-quadrant compass rose, break them into milestones and tasks, log every deviation, and review each week's wake before setting the next heading.

✨ Features

• Four-quadrant compass — Career / Learning / Health / Life. Drag goals between quadrants to re-anchor where they belong.
• Three-tier goals — Goal → Milestone → Task. Progress rolls up automatically. Tasks carry due date / priority / estimate / tags for finer planning.
• Voyage page, two views — Timeline for the narrative, Kanban for the flow. Drag to move tasks across states.
• Calendar view — Monthly grid aggregating goal deadlines, milestone due dates, task due dates, and log density onto one chart. Monday-first, prev/next/today nav.
• Captain's log — Record mood, energy, and tags. Link entries to goals. Review drift on your own schedule.
• Helm command palette — ⌘K to jump anywhere or search across goals, tasks, and logs. Mouse optional.
• Lighthouse signals — Deadline and achievement notifications. Generated on demand with fingerprint dedup, no cron worker needed. Per-type toggles and quiet hours (cross-midnight supported).
• Weekly review + monthly overview — Auto-aggregated highlights and metrics for each week, plus your own reflections. Below it, a month-by-month roll-up covers goals / tasks / focus minutes / habit check-in days / top tags, with prev/next navigation.
• Spyglass search — Full-text search across goals, tasks, and logs. Title hits rank first. All queries scoped by userId.
• Focus cabin — Pomodoro sessions (25/5/15 presets or custom 5–120 min) with optional task linking. Today/week stats auto-tallied, plus weekday and hour-of-day distribution charts.
• Daily anchors — Habit tracker with streaks and a 52×7 yearly heatmap. Group habits by morning / afternoon / evening / anytime.
• Tags across goals / tasks / logs — Cross-cutting taxonomy for the spyglass, calendar, and monthly overview.
• Two themes — Deep-sea navy (default) and parchment ivory. Server-rendered, no theme flash.
• PWA — Installable, offline-capable via service worker, maskable icon, manifest shortcuts.
• Nautical instrument aesthetic — Compass rose, brass gold, ivory white, monospace figures. Not yet another generic SaaS template.

🛠 Tech stack

Layer	Choice
Framework	Next.js 14 App Router (full-stack, Server Components)
Language	TypeScript strict mode
Styling	Tailwind CSS 3.4 + CSS variable theming
Data	Prisma 5 + PostgreSQL 16
Auth	NextAuth.js 4 (JWT, Credentials + OAuth ready)
Animation	Framer Motion 11 (respects prefers-reduced-motion)
Testing	Vitest (524 unit/API tests) + Playwright (E2E)
Deploy	Docker Compose + Caddy (automatic HTTPS)

📐 Architecture

src/
├── app/                    # App Router routes
│   ├── (auth)/             # sign in / sign up / reset password
│   ├── dashboard/          # today's focus + stats
│   ├── compass/            # four-quadrant drag canvas
│   ├── voyage/             # timeline + kanban dual view
│   ├── calendar/           # monthly deadline + log density grid
│   ├── logbook/            # captain's log timeline + editor
│   ├── review/             # weekly review + monthly overview
│   ├── focus/              # pomodoro cabin + session history + charts
│   ├── anchors/            # habit tracker with streaks + heatmap
│   ├── onboarding/         # 4-step new user wizard
│   ├── profile/            # account / security / preferences / data
│   └── api/                # REST endpoints (notifications / search / reviews / focus / habits / calendar)
├── components/
│   ├── compass/            # compass canvas, goal cards
│   ├── voyage/             # timeline, kanban, task dialog (due/priority/estimate/tags)
│   ├── calendar/           # monthly grid view
│   ├── logbook/            # log timeline, editor, tag input
│   ├── review/             # weekly review editor
│   ├── focus/              # pomodoro timer + session list + distribution charts
│   ├── habits/             # habit list + check-in + streak badge + 52×7 heatmap
│   ├── command-palette/    # helm command palette
│   ├── notifications/      # lighthouse signal center
│   ├── shortcuts/          # helm shortcut help
│   ├── profile/            # profile sections (incl. granular notification prefs)
│   ├── ui/                 # Toast / Confirm / Skeleton / animated number
│   └── AppShell.tsx        # nav shell (palette + notifications + shortcuts)
└── lib/
    ├── services/           # business logic (transactions, state machines, on-demand generation)
    ├── validations.ts      # Zod schemas (all `.strict()`)
    ├── shortcuts.ts        # server-safe shortcut registry
    ├── compass.ts          # quadrant / status metadata
    ├── session.ts          # auth helpers
    ├── rate-limit.ts       # in-memory rate limiter
    └── prisma.ts           # Prisma singleton

Data model:

User ─┬─ Goal ── Milestone ── Task     # tags on Goal + Task; dueDate/priority/estimate on Task
      ├─ Log ←→ GoalLogs ←→ Goal       # tags on Log
      ├─ Notification                  # lighthouse signals (deadline / achievement / system)
      ├─ WeeklyReview                  # one per ISO week (unique constraint)
      ├─ FocusSession                  # pomodoro sessions, optionally linked to a Task
      ├─ Habit ── HabitCheck           # daily anchors (one check per habit per day)
      └─ PasswordReset

🎨 Design language

Compass has its own visual point of view — it is not a generic template.

Color	Hex	Used for
Deep-sea navy	#0B1426	default background, star-chart night
Ivory	#F5F1E8	primary text
Brass gold	#C9A227	accent, progress, compass needle
Tide teal	#4A7C82	secondary state
Coral	#D97757	warning, destructive actions
Starlight silver	#A8B4C4	secondary text, skeletons

• Type: Cormorant Garamond (serif headings) / Source Sans 3 (body) / JetBrains Mono (figures)
• Texture: glass panels, brass glow, rotating compass rose, star-chart backdrop

🚀 Quick start

Prerequisites

• Node.js ≥ 20
• pnpm ≥ 9
• PostgreSQL ≥ 14

Local development

git clone https://github.com/MS33834/compass.git
cd compass
pnpm install
cp .env.example .env          # fill in DATABASE_URL / NEXTAUTH_SECRET / SMTP / OAuth
pnpm db:generate              # generate Prisma Client
pnpm db:migrate               # create tables
pnpm db:seed                  # optional: load sample data
pnpm dev                      # http://localhost:3000

Testing

pnpm typecheck                # TypeScript strict check
pnpm lint                     # ESLint
pnpm test                     # unit + API integration tests (524 cases)
pnpm test:e2e                 # E2E (requires running DB + browser install)
pnpm build                    # production build

🐳 Production deploy

One-shot Docker Compose (app + Postgres + Caddy auto-SSL + scheduled backups):

cp .env.production.example .env.production   # fill in domain / passwords / SMTP
docker compose up -d
./scripts/smoke-test.sh                      # pre-launch smoke test

Full deploy, backup/restore, and rollback procedures: see DEPLOY.md.

🔒 Security

• Auth: NextAuth JWT. Middleware protects every authenticated route.
• Rate limiting: sign-up 5/15min, writes 30/min, password change 10/min, export 5/min.
• Data isolation: every query's where carries userId — IDOR-resistant by construction.
• Input validation: every API input runs through a Zod .strict() schema; UUID params validated.
• Passwords: bcrypt cost 12, never serialized or returned.
• XSS: log content rendered as plain text; exports force attachment download.

Security audit report: docs/SECURITY-AUDIT.md. Vulnerability disclosure policy: SECURITY.md.

📊 Roadmap

Phase	Scope	Status
0	Foundation	✅
1	Landing + auth	✅
2	Dashboard	✅
3	Compass quadrants	✅
4	Voyage (milestones + tasks)	✅
5	Logbook	✅
6	Onboarding + profile	✅
7	Interaction polish	✅
8	Test QA	✅
9	Production deploy	✅
10	Iteration (OAuth / charts / PWA / i18n / gestures / templates / import-export)	✅
11	Productivity layer (command palette + notifications + review + search)	✅
12	Deep work layer (focus cabin + daily anchors)	✅
13	Content enrichment (calendar / task depth / tags / habit heatmap / focus charts / granular notifications / monthly overview / public asset polish)	✅

📸 Screenshots

The Compass UI speaks for itself. Drop your screenshots into docs/screenshots/ and reference them here once you have a running deploy.

docs/screenshots/
├── landing.png          # hero with rotating compass rose
├── compass.png          # four-quadrant drag canvas
├── voyage-kanban.png    # kanban view with task dialog (due / priority / tags)
├── calendar.png         # monthly deadline + log density grid
├── focus-charts.png     # weekday + hour-of-day distribution
├── habit-heatmap.png    # 52×7 yearly check-in heatmap
└── review-monthly.png   # weekly review + monthly overview

Tip: pnpm dev → log in → visit each route → browser screenshot at 1440×900.

📁 Documentation

All deep docs are English-primary with a Chinese mirror. Toggle links live at the top of each file.

Doc	What's inside	中文版
USAGE.md	User guide — every module walkthrough	中文
DEPLOY.md	Production deployment handbook	中文
DEVELOPMENT.md	Local dev setup and conventions	中文
CHANGELOG.md	Release history (Keep a Changelog)	—
CONTRIBUTING.md	How to contribute	—
SECURITY.md	Vulnerability disclosure policy	—
docs/SECURITY-AUDIT.md	Security audit report	中文
docs/ACCESSIBILITY-AUDIT.md	Accessibility audit report	中文
docs/PERFORMANCE-AUDIT.md	Performance audit report	中文
docs/CODE-AUDIT.md	Code quality audit report	中文

🤝 Contributing

Contributions welcome — bug reports, feature ideas, docs, or code.

• 📖 Contributing guide
• 🛡️ Code of conduct
• 🔒 Security policy
• 📋 Issue templates
• 💬 Discussions

Acknowledgements

Thanks to everyone who has shipped code, filed issues, or joined the discussion. 🧭

Contributors

📝 License

Released under the MIT License.

Copyright © 2026 Compass Contributors

---

Compass · May you always know your heading, even on open water.

⭐ If Compass helps you, a star goes a long way.