Sergeant

Last validated: 2026-06-09 by @claude. Next review: 2026-09-07. Status: Active

Гроші, тіло, звички, їжа — в одному додатку. Local-first. Приватно. Sergeant — це особистий hub для дисциплінованої щоденки: один додаток замість п'яти, з AI-коучем, що бачить весь твій день.

AI coding agent or tool? Read AGENTS.md — repo policy, hard rules, and the agent operating system (skills, playbooks). Sub-tree quick references: apps/web/AGENTS.md, apps/server/AGENTS.md, apps/mobile/AGENTS.md.

Hero screenshot pending — capture-інструкції в docs/assets/. Виконавець може закрити цей пункт у follow-up PR через 1280×720 PNG з cold-start dashboard-у.

Що це?

Sergeant обʼєднує 5 модулів, які раніше жили в окремих додатках:

Модуль	Що робить
Фінік	Фінанси: Monobank-інтеграція, транзакції, бюджети, борги
Фізрук	Фітнес: тренування, підходи, біометрія, планування
Рутина	Звички: трекер habit-ів, стріки, календар
Харчування	Їжа: meal-логи, сканер штрих-кодів, AI-аналіз
HubChat	AI-помічник: чат з Claude, який виконує дії через розмову

Web (PWA), iOS, Android. Працює офлайн. Дані — на твоєму пристрої.

Спробувати

Локальний запуск: § Quickstart нижче — ~5 хвилин від клонування до live UI на http://localhost:5173.
Демо-режим без реєстрації: після bootstrap відкрий http://localhost:5173/welcome?demo=1 — побачиш приклад інтерфейсу з seed-даними, без створення акаунта. (Public production URL ще не лінкується — додасться, коли launch-readiness допиляється; див. docs/01-product/launch/business/04-launch-readiness.md).
Огляд продукту: docs/01-product/launch/business/01-monetization-and-pricing.md — бізнес-модель + позиціонування.
Поточний стан FTUX: docs/01-product/launch/product-os/ftux-master-tracker.md — sprint registry + відкриті проблеми.

Хочеш контриб'ютити, а не просто юзати? → § For Contributors and Agents у кінці.

Tech Stack

Language: TypeScript 6
Frontend (web): React 18, Vite, Tailwind CSS, TanStack Query
Mobile: Expo 52, React Native 0.76, NativeWind
Mobile shell: Capacitor (web wrapper for native distribution)
Backend: Express.js, PostgreSQL 16, Better Auth (authentication)
AI: Anthropic Claude API, Voyage AI (embeddings)
Monorepo: Turborepo, pnpm 9.15.1
Testing: Vitest, Testing Library, MSW (API mocking), Testcontainers (real Postgres in tests), Playwright (E2E)
Linting: ESLint 9, Prettier, commitlint, Husky (pre-commit hooks)
CI/CD: GitHub Actions
Deploy: Vercel (frontend), Railway (backend + PostgreSQL)
Monitoring: Sentry (errors), PostHog (analytics), Grafana (metrics), Web Vitals
Telegram bot: grammy + Anthropic (internal ops)

What is in the repo

Apps (`apps/`)

Directory	What it is	Stack	Deployed to
`apps/web`	Web app (primary UI)	React + Vite + Tailwind	Vercel
`apps/server`	API server (backend)	Express + PostgreSQL	Railway
`apps/mobile`	Mobile app (native)	Expo + React Native	App Store / Google Play
`apps/mobile-shell`	Mobile app (web wrapper)	Capacitor	App Store / Google Play
`tools/openclaw`	Telegram bot (internal)	grammy + Anthropic	Railway

Tooling (`tools/`)

Non-app workspaces that support lint / build invariants. Not deployed.

Directory	What it is	Stack
`tools/tsconfig-guard`	Strict TS-flag guard (Hard Rule #19); gates `lint`	TypeScript

Packages (`packages/`)

Packages are shared code reused across apps. Instead of copy-pasting between web and mobile, we put shared code in packages/ and import from there.

Package	Purpose
`@sergeant/shared`	Shared business logic, Zod schemas, types — used by ALL apps
`@sergeant/api-client`	Type-safe HTTP client for talking to the server
`@sergeant/config`	Shared configs (ESLint, TypeScript, etc.)
`@sergeant/design-tokens`	Design tokens, Tailwind preset, colors, typography
`@sergeant/insights`	Cross-module analytics (pure functions over data)
`@sergeant/finyk-domain`	Finance domain logic (calculations, amount formatting)
`@sergeant/fizruk-domain`	Fitness domain logic (calories, load calculations)
`@sergeant/nutrition-domain`	Nutrition domain logic
`@sergeant/routine-domain`	Habits domain logic
`@sergeant/db-schema`	Drizzle schemas, migrations, and sync helpers
`@sergeant/openclaw-plugin`	OpenClaw Gateway tools/hooks plugin (Gateway-only — NOT consumed by web/mobile)
`eslint-plugin-sergeant-design`	Custom ESLint rules for the design system

Architecture overview lives in docs/02-engineering/architecture/README.md; the full doc index lives in docs/README.md.

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────────┐
│   apps/web      │     │   apps/mobile   │     │   apps/mobile-shell │
│ (React + Vite)  │     │ (Expo + RN)     │     │ (Capacitor)         │
└───────┬─────────┘     └───────┬─────────┘     └───────┬─────────────┘
        │                       │                       │
        └───────────┬───────────┘                       │
                    │                                   │
                    ▼                                   │
        ┌───────────────────────┐                       │
        │ packages/api-client   │◀──────────────────────┘
        │ (HTTP client)         │
        └───────────┬───────────┘
                    │
                    ▼
        ┌───────────────────────┐
        │   apps/server         │
        │ (Express + Better Auth│
        │  + Anthropic Claude)  │
        └───────────┬───────────┘
                    │
                    ▼
        ┌───────────────────────┐     ┌─────────────────┐
        │   PostgreSQL          │     │  tools/openclaw   │
        │ (Railway / Docker)    │     │  (Telegram bot)  │
        └───────────────────────┘     └─────────────────┘

Fizruk and Routine modules follow a local-first approach: data is stored locally first (localStorage on web, MMKV on mobile), then synced to the server via CloudSync using LWW (Last-Write-Wins) conflict resolution. The app works offline.

Prerequisites

Node.js 20.x (recommended via Volta)
pnpm 9.15.1 (npm install -g pnpm@9.15.1)
Docker (for local PostgreSQL)

Quickstart

Fast path: `pnpm bootstrap` (~5 хв)

git clone https://github.com/Skords-01/Sergeant.git
cd Sergeant
corepack enable && corepack prepare pnpm@9.15.1 --activate   # one-time
pnpm bootstrap

pnpm bootstrap робить:

Перевіряє Node 20.x + pnpm 9.15.1 + Docker daemon (з підказкою як виправити, якщо щось не так).
pnpm install --frozen-lockfile (skip-неться, якщо node_modules свіжий).
cp .env.example .env, якщо .env ще нема (existing .env не чіпається).
pnpm dev:db — піднімає Postgres у Docker і прокачує всі міграції.
Друкує блок «next steps» з командами для запуску API + Web.

Тільки prerequisites без install/docker: pnpm bootstrap:check.

Прапорці: --skip-install, --skip-db (для CI / повторних прогонів). Кроки нижче — manual fallback, якщо bootstrap не запускається.

Manual fallback

1. Clone and install

git clone https://github.com/Skords-01/Sergeant.git
cd Sergeant
pnpm install --frozen-lockfile

--frozen-lockfile installs the exact versions recorded in the lockfile without modifying it.

2. Configure environment variables

cp .env.example .env

Open .env in your editor. Most values are pre-filled for local development. Key variables:

Variable	Required?	What it does
`DATABASE_URL`	Yes	Database URL (Docker default: `postgresql://hub:hub@localhost:5432/hub`)
`BETTER_AUTH_SECRET`	Yes	Session cookie signing secret (min 32 characters)
`ANTHROPIC_API_KEY`	For AI	Claude API key — HubChat won't work without it
`GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET`	No	Google OAuth — without these the "Sign in with Google" button won't appear
`VITE_API_PROXY_TARGET`	No	Dev proxy target (default `http://127.0.0.1:3000`)
Others	No	See `docs/02-engineering/integrations/env-vars.md` — full reference for all 100+ optional variables (Sentry, PostHog, Voyage, Mono, OpenClaw, AI quotas, …)

3. Start the database

pnpm dev:db

This runs docker compose up -d + pnpm db:migrate — starts PostgreSQL 16 in a Docker container and runs all SQL migrations.

To stop the database: pnpm db:down (or docker compose down).

4. Start the server and web app

# In one terminal:
pnpm dev:server

# In another terminal:
pnpm dev:web

Local URLs:

Web: http://localhost:5173
API: http://localhost:3000

5. (Optional) Mobile app

# Expo (React Native)
pnpm --filter @sergeant/mobile start

# Capacitor (web wrapper → native)
# First build web, then open in Xcode / Android Studio

6. (Optional) Telegram bot

pnpm --filter @sergeant/openclaw dev

Requires a Telegram Bot Token in tools/openclaw/.env.

Core commands

Command	What it does
`pnpm dev:web`	Start the web app (Vite dev server)
`pnpm dev:server`	Start the API server (Express)
`pnpm dev:db`	Start Docker + run migrations
`pnpm lint`	Lint code (ESLint + imports + OpenAPI)
`pnpm typecheck`	TypeScript type checking
`pnpm test`	Run all tests
`pnpm test:coverage`	Tests with coverage report
`pnpm format`	Format code (Prettier)
`pnpm format:check`	Check formatting without changing files
`pnpm build`	Build all apps
`pnpm build:web`	Build web only
`pnpm check`	Full verification: format + lint + typecheck + test + build
`pnpm db:up`	Start Docker with PostgreSQL
`pnpm db:down`	Stop Docker
`pnpm db:migrate`	Run SQL migrations
`pnpm gen`	Generate boilerplate (plop)
`pnpm gen:adr`	Generate a new ADR (Architecture Decision Record)
`pnpm docs:check-links`	Verify documentation links
`pnpm bootstrap`	One-shot dev bootstrap (verify env + install + docker + db)
`pnpm bootstrap:check`	Verify Node/pnpm/Docker prerequisites only

Testing

# All tests (via Turborepo)
pnpm test

# Tests for a specific package
pnpm --filter @sergeant/web test
pnpm --filter @sergeant/server test

# Tests with coverage
pnpm test:coverage

# E2E / a11y tests
pnpm test:a11y

Test stacks by surface:

Web: Vitest + MSW + React Testing Library
Server: Vitest + Testcontainers (real Postgres)
Mobile: Jest

Deployment

Service	Deployed to	How
Web (frontend)	Vercel	Auto preview deploy on every PR, production on merge to `main`
Server (API)	Railway	Dockerfile.api, pre-deploy migrations
Mobile (Expo)	EAS Build → TestFlight / Google Play	Via Expo Application Services
Mobile Shell (Capacitor)	App Store / Google Play	Via Capacitor build

Integrations

Service	What it does	Required?
Monobank	Transactions, balances, webhooks	No — Finyk works without it
Anthropic Claude	AI chat (HubChat)	Yes for AI, no for the rest
Voyage AI	Embeddings for AI memory (pgvector)	No
OpenFoodFacts	Product search by barcode	No — falls back to USDA
USDA FDC	Nutrient search by barcode	No — falls back to DEMO_KEY
Groq Whisper	Voice input → text	No — falls back to Web Speech API
PostHog	Product analytics	No
Sentry	Error monitoring	No
Resend	Email (verification, password reset)	No
Google OAuth	"Sign in with Google"	No
n8n	Workflow automation (ops)	No

Troubleshooting

Symptom	Cause	Fix
`pnpm install` fails with lockfile error	Wrong pnpm version	`npm i -g pnpm@9.15.1`
`pnpm dev:db` doesn't work	Docker not running	Start Docker Desktop, then retry
Port 5432 busy	Another Postgres or container	`docker ps` → stop conflicting container
API returns "401 Unauthorized"	No session or `BETTER_AUTH_SECRET` mismatch	Restart server after changing `.env`, re-register
HubChat says "Unknown action"	`max_tokens` cut off JSON tool-call	Don't reduce `max_tokens` without testing
lint-staged fails on commit	Code didn't pass ESLint / Prettier	Fix errors, `pnpm lint --fix`
Streaks reset unexpectedly	Used UTC instead of Kyiv timezone	Always calculate "today" via `Europe/Kyiv`
Numbers from API come as strings	bigint → string (PostgreSQL pg driver)	`Number(r.id)` in serializer

Feature flags

Feature flags are managed via docs/04-governance/governance/feature-flags.md. Each flag controls the visibility of a specific feature.

Observability

Monitoring is described in docs/03-operations/observability/README.md. Key components: Sentry (errors), PostHog (analytics), Prometheus/Grafana (metrics), Web Vitals (frontend performance).

Documentation map

Directory	Contents
`docs/04-governance/adr/`	Architecture Decision Records — why we chose what we chose
`docs/02-engineering/api/`	OpenAPI contracts, API documentation
`docs/02-engineering/architecture/`	Repository map, platforms, service catalog
`docs/90-work/audits/`	UX/UI audits, typography, design reviews
`docs/03-operations/deploy/`	Deployment instructions
`docs/05-design/design/`	Design system: brandbook, colors, module accents
`docs/04-governance/governance/`	Hard rules, review checklist, release policy
`docs/02-engineering/integrations/`	Monobank, Railway, Vercel, Renovate, Voyage
`docs/01-product/launch/`	Monetization, GTM, launch readiness
`docs/02-engineering/mobile/`	Capacitor, deep links, React Native migration
`docs/03-operations/observability/`	SLO, dashboards, metrics, runbook
`docs/90-work/planning/`	Roadmaps, AI improvements, dev stack roadmap
`docs/00-start/playbooks/`	Step-by-step recipes (add an endpoint, do a hotfix)
`docs/03-operations/postmortems/`	Incident post-mortems
`docs/04-governance/security/`	Access policy, disaster recovery, security audit
`docs/00-start/agents/`	AI agent system: skill catalog, workflows
`docs/90-work/tech-debt/`	Tech debt registries (frontend, backend, mobile)

Roadmap: docs/90-work/planning/README.md. Tech debt: docs/90-work/tech-debt/README.md.

For Contributors and Agents

Humans: start with CONTRIBUTING.md.
Agents: start with AGENTS.md and docs/00-start/agents/agent-skills-catalog.md.
Full docs index (genre-grouped — informational / trackers / archive): docs/README.md.
What is currently in flight across all 7 trackers (auto-rollup, CI drift gate): docs/open-work.md.
Repeatable execution recipes: docs/00-start/playbooks/README.md.
Governance and hard rules matrix: docs/04-governance/governance/README.md.
Runtime inventory, release, incident, and recovery surfaces: docs/02-engineering/architecture/service-catalog.md, docs/04-governance/security/disaster-recovery.md.

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 6,097 Commits
.agents		.agents
.claude		.claude
.codex		.codex
.devcontainer		.devcontainer
.github		.github
.husky		.husky
.tech-debt		.tech-debt
.telemetry		.telemetry
apps		apps
docs		docs
mockups		mockups
ops		ops
packages		packages
patches		patches
plans		plans
plop-templates		plop-templates
scripts		scripts
tools/tsconfig-guard		tools/tsconfig-guard
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.git-blame-ignore-revs		.git-blame-ignore-revs
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitleaksignore		.gitleaksignore
.mcp.json		.mcp.json
.npmrc		.npmrc
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
.trivyignore		.trivyignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
DEVIN.md		DEVIN.md
Dockerfile.api		Dockerfile.api
Dockerfile.openclaw-gateway		Dockerfile.openclaw-gateway
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
THIRD_PARTY_LICENSES.md		THIRD_PARTY_LICENSES.md
commitlint.config.js		commitlint.config.js
docker-compose.yml		docker-compose.yml
eslint.baseline.js		eslint.baseline.js
eslint.config.js		eslint.config.js
eslint.cross-surface.js		eslint.cross-surface.js
eslint.mobile.js		eslint.mobile.js
eslint.packages.js		eslint.packages.js
eslint.server.js		eslint.server.js
eslint.shell.js		eslint.shell.js
eslint.web.js		eslint.web.js
knip.json		knip.json
package.json		package.json
plopfile.mjs		plopfile.mjs
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-overrides.md		pnpm-overrides.md
pnpm-workspace.yaml		pnpm-workspace.yaml
railway.openclaw-gateway.toml		railway.openclaw-gateway.toml
railway.toml		railway.toml
renovate.json		renovate.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

Sergeant

Що це?

Спробувати

Tech Stack

What is in the repo

Apps (apps/)

Tooling (tools/)

Packages (packages/)

Architecture

Prerequisites

Quickstart

Fast path: pnpm bootstrap (~5 хв)

Manual fallback

1. Clone and install

2. Configure environment variables

3. Start the database

4. Start the server and web app

5. (Optional) Mobile app

6. (Optional) Telegram bot

Core commands

Testing

Deployment

Integrations

Troubleshooting

Feature flags

Observability

Documentation map

For Contributors and Agents

License

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Apps (`apps/`)

Tooling (`tools/`)

Packages (`packages/`)

Fast path: `pnpm bootstrap` (~5 хв)

Packages