Local development

Use this stack while you instrument an application locally. Hosted Flowmark is the product path; these services are what the repository runs today.

Services to operateCopy Anchor Link

• Flowmark API: accepts private server events and public browser events, hosts Better Auth, and authorizes dashboard reads. Configure its PostgreSQL DATABASE_URL and a BETTER_AUTH_SECRET for hosted use. Instrumented applications use FLOWMARK_API_URL and FLOWMARK_API_KEY to connect to this API; those are SDK client settings, not a dashboard login.
• PostgreSQL: stores users, sessions, projects, hashed keys, workflows, runs, and append-only event history. Back up and protect this database as telemetry data.
• Dashboard: people sign in with email and password. The dashboard same-origin-proxies /api/auth/*, /api/register, and /api/trpc/* so the session cookie stays first-party. Reads are scoped to projects the signed-in user belongs to.

Sign-up creates a workspace, project, and the first server write key. The repository's seeded local@dev account is a loopback fixture for the operations project, not a production owner. Password reset is not available until you add email delivery. Do not expose a dashboard configured with demo mode or a shared demo credential to the public internet.

Configure keys safelyCopy Anchor Link

Keep private server-write keys in server-side secret storage. Never place them in browser bundles, frontend environment variables, or build logs. Browser instrumentation requires a separate public browser key, restricted to exact origins and rate limited per key; its events remain untrusted input. Programmatic API reads may use a project read key; the dashboard itself uses the signed-in session.

Before handling real data, add your own authentication, rate limiting, provisioning, backups, retention and deletion policy, monitoring, and key rotation. Test these controls in a non-production project. Do not use the repository's public local-demo credentials with customer data.

Local development harnessCopy Anchor Link

The repository's invoice, inventory and order operations harness is a loopback fixture for contributors. It uses fixed development projects and development-only credentials. Setup, ports, and PostgreSQL workflow live in the internal contributor guide.