New operator
Scope and Model → Quickstart Flow → Walkthrough
Use this path to validate end-to-end setup before deep tuning.
Powerhour Docs
Documentation
This documentation is written for self-hosted operators. Route references describe in-app paths in your own deployment (for example /transactions), not a hosted web app endpoint.
Scope and Model
Domain separation is explicit:
- Docs domain: https://docs.powerhour.dev (documentation pages).
- Marketing domain: https://powerhour.dev (features, security, deployment marketing content).
- Product runtime: self-hosted instance controlled by deployer; route examples in this doc are app routes, not hosted URLs.
Reader paths
Security reviewer
Security Model → Operations and Runtime → FAQ
Use this path to inspect controls, boundaries, and practical caveats.
Engineer contributor
Core Modules → API Domains → Implementation Map
Use this path to map features to code ownership quickly.
Product Highlights
Quick orientation for non-engineering readers, with direct route context for operators and developers.
Unified dashboard
Daily financial posture with net worth, balances, category movement, and credit utilization in one command surface.
/, /accounts, /accounts/[id]
Ticker AI diagnostics
Ask direct financial questions, compare trend windows, audit recurring costs, and trigger report generation flows.
/ (embedded), floating chat on dashboard routes
Planner workflows
Mode-driven planning for travel, savings targets, and spend reduction with persisted conversations.
/budget-planner, /projections
Transactions and groups
Search and filter transaction history, then organize records into groups for trip/project analysis.
/transactions, /transactions/groups, /transactions/groups/[id]
Recurring and subscription control
Detect recurring items, flag inactive subscriptions, estimate monthly/annual risk, and deactivate noise quickly.
/subscriptions, /projections
Security-first data boundaries
Encrypted tokens, restricted agent views, verified webhooks, and audit events for critical operations.
/settings, /api/webhooks/plaid, /api/audit-log
Quickstart Flow
- 1. Authenticate at
/login. - 2. Link an institution in
/settings. - 3. Trigger manual sync from
/settings. - 4. Validate dashboard and accounts:
/,/accounts. - 5. Run transaction and recurring checks:
/transactions,/subscriptions,/projections.
Core Modules
| Module | In-app routes | Purpose |
|---|---|---|
| Dashboard and analytics | /, /accounts, /accounts/[id] | Consolidated financial posture: KPI cards, net worth, account views, balance history, and trend visualizations. |
| Transactions and grouping | /transactions, /transactions/groups, /transactions/groups/[id] | Search, filters, pagination, group assignment, and suggestion workflows for transaction-level analysis. |
| Projections and recurring | /projections, /subscriptions | Recurring detection, shortfall forecasting, subscription audit, and savings trajectory views. |
| Budgeting and planning | /budgets, /budget-planner | AI-generated budget goals plus mode-based planner workflows for travel, savings, and spend reduction. |
| Settings and control plane | /settings | Scheduler toggles, institution management, sync controls, password changes, and audit event visibility. |
API Domains
Auth and session
/api/auth/login, /api/auth/logout, /api/auth/me, /api/auth/change-password
Dashboard analytics
/api/dashboard/summary, /api/dashboard/*-history, /api/dashboard/spending-trends, /api/dashboard/category-trends, /api/dashboard/channel-trends, /api/dashboard/credit-utilization
Accounts and transactions
/api/accounts, /api/accounts/[id], /api/transactions, /api/transactions/summary, /api/transactions/daily, /api/transactions/merchants
Budgets, plans, projections
/api/budget-goals, /api/budget-goals/generate, /api/budget-plans, /api/projections, /api/recurring, /api/savings-targets, /api/subscriptions
Agent execution
/api/ai/chat, /api/ai/budget-planner, /api/ai/report
Plaid and sync
/api/plaid/link-token, /api/plaid/exchange-token, /api/plaid/institutions, /api/sync, /api/webhooks/plaid
Security Model
- Encrypted token storage and secure field handling (`lib/crypto.ts`, `lib/crypto-fields.ts`).
- Session + request middleware gating and authenticated API throttling (`middleware.ts`).
- Agent-safe database views and schema-level separation (`lib/db/views.ts`, `lib/db/migrations/0000_agent_views.sql`).
- Plaid webhook verification and sync boundary control (`lib/plaid/webhooks.ts`, `lib/plaid/sync.ts`).
- Audit event capture for critical actions (`lib/audit-log.ts`, `app/api/audit-log/route.ts`).
Operations and Runtime
- Startup initialization handled by
instrumentation.ts. - Scheduler jobs configured in
lib/scheduler.ts. - Environment and bootstrap automation in
scripts/setup.js. - Container runtime and reverse proxy in
docker/*. - Health and control routes under
/api/healthand/api/settings/scheduler.
Implementation Map
| Area | Primary files |
|---|---|
| Runtime and routing | app/layout.tsx, app/(dashboard)/layout.tsx, middleware.ts, instrumentation.ts |
| Pages | app/(auth)/login/page.tsx and app/(dashboard)/*/page.tsx |
| API routes | app/api/**/route.ts |
| UI composition | components/dashboard/*, components/chat/*, components/budget-planner/*, components/charts/* |
| State and hooks | hooks/use-dashboard.ts, hooks/use-transactions.ts, hooks/use-accounts.ts, hooks/use-expense-groups.ts |
| AI and tools | lib/agent/agent.ts, lib/agent/budget-planner-agent.ts, lib/agent/tools/* |
| Domain logic | lib/projections.ts, lib/recurring.ts, lib/savings-projections.ts, lib/savings-targets.ts |
| Data model | lib/db/schema.ts, lib/db/views.ts, lib/db/migrations/* |
| Infra and deploy | docker/Dockerfile, docker/docker-compose.yml, docker/nginx/nginx.conf, scripts/* |
Next Reading
- Walkthroughs for step-by-step operational flows.
- FAQ for setup, security, and troubleshooting questions.