Living document

App status, architecture, and direction

Clarity is a web application for founders, bookkeepers, and finance operators who need multi-entity visibility without traditional accounting software weight. Bank data flows in through Plaid; tagging and rules organize activity by company; AI assists with summaries and classification; Stripe handles subscriptions. This page summarizes how the repo is structured today and where the product is headed.

Essence

What the app does

Users authenticate with Supabase Auth (JWT in the browser, validated on the Node server). They connect institutions via Plaid, sync transactions and balances, assign company tags to accounts and transactions, and view dashboards, cashflow, reports, and planning views. An OpenAI-backed layer exposes metrics, chat, insights, and category suggestions. Stripe manages checkout, the customer portal, and webhooks for subscription state. Plan limits (starter / growth / pro) gate account counts, company tags, and planning access via planLimits.js on the client.

Current status

Shipping shape in this repository

Backend

Single Express app in server.js with modular routers under routes/ (AI, reports, tags, transactions). Hardened session cookies, Helmet CSP, rate limits on writes, Plaid and Stripe integrations, cron hook for refresh.

Frontend

Static HTML + JS in public/. Legacy workspace pages remain the default for most flows. A v2 shell (shared auth, API client, layout CSS) is documented in docs/clarity-frontend-architecture.md with all workspace pages now on the v2 shell.

Data

Supabase for Postgres-backed app data and auth user resolution; connect-pg-simple for session storage in Postgres; schema health checks and tests under test/.

Workflows

Primary user journeys

Acquisition: Marketing site (index.html), FAQ, support, invest deck → signup.html → Supabase sign-up → redirect to onboarding.
Onboarding checklist: Billing (Stripe) → bank connections (accounts.html, Plaid link) → company tagging in settings → dashboard for insights.
Daily use: Review dashboard.html, drill into transactions.html, use reports.html / cashflow.html / planning.html, ask questions in ai.html, manage billing.html and settings.html.
Automation: Transaction rules and tag suggestions (bulk accept/reject APIs), optional AI bulk categorization, reconnect flows when Plaid items need update (/status/needs-reconnect).
Admin: Restricted routes under /admin/* and admin HTML for operator tools.

User interface & features

Surface map (`public/*.html`)

Workspace

dashboard.html — home metrics and entry to insights
transactions.html / transactions2.html — ledger-style views
accounts.html — Plaid connections, balances
reports.html, cashflow.html, planning.html
ai.html — AI assistant and insights
settings.html, billing.html
Legacy suffixed pages (e.g. *-legacy.html) for rollback / comparison

Auth, growth, misc

login.html, signup.html, onboarding.html
index.html, beta.html, faq.html, support.html, invest.html
mobile.html, testing.html, admin.html, admin-backend.html

Shared client layer: public/js/core/auth.js (ClarityAuth), public/js/core/api.js (ClarityApi), public/js/ui/format.js, shell.js, v2-page.js; styles in clarity-v2-shell.css and built Tailwind clarity-tailwind.css.

Roadmap (indicative)

Direction implied by codebase and product materials

These items are inferred from architecture notes and internal planning copy (for example invest.html use-of-funds); they are not a committed schedule.

Expand the v2 shell to additional workspace pages so navigation, typography, and API usage stay consistent end-to-end.
AI Insights iteration: richer saved insights, clearer guardrails, and tighter coupling to tagged transaction data.
Mobile responsiveness pass across high-traffic legacy pages.
Onboarding polish aligned with the refreshed visual system (see updated onboarding).
Infrastructure: cost-aware Plaid usage, Supabase scaling patterns, security review / compliance groundwork.

Stack

Technology summary

Runtime: Node.js, Express 4
Database: PostgreSQL via pg (sessions + app), Supabase JS client for user-scoped data
Auth: Supabase Auth (JWT bearer to API), express-session for server-side session where used
Integrations: Plaid, Stripe, OpenAI
Frontend assets: Tailwind CSS 4 (CLI build), vanilla JS modules, Recharts where charts are used
Security: Helmet, CORS, CSRF (csurf) where applicable, rate limiting, structured request logging with request IDs
Testing: Node native test runner (npm test)

Update this file when major routes, pages, or integrations change so newcomers have a single HTML overview.