@arcforgelabs/flow 0.0.0-stage → 2026.10.18

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samuel Rodda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# Flow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Flow is invoicing, bill entry and a financial dashboard for labs that make
+work to order, first for dental labs. Seazona (the lab's case system) is a
+bundled integration, and Xero is an optional one. See `VISION.md`.
+
+Flow is maintained by Arc Forge Labs at
+[arcforgelabs/flow](https://github.com/arcforgelabs/flow).
+
+Licence: MIT (`LICENSE`).
+
+## Status
+
+This repository is the new home of Flow, with a new history. Code moves here
+from an earlier private codebase one module at a time (`CONTRIBUTING.md`,
+"Porting from the earlier codebase"). Today it holds the repository's rules,
+CI, the release track (npm, container image and GitHub Release, on a beta and
+a stable channel), the integration port, a health check, Clerk sign-in with
+roles kept in Flow, and the first part of the core: the PostgreSQL data model
+for organisations, contacts, the price list and invoices. It is not ready to
+run a lab.
+
+## Documentation
+
+| Document | What it is for |
+| --- | --- |
+| `VISION.md` | What Flow is for, the core and its integrations, and what it will not do |
+| `AGENTS.md` | Agent entry point (`CLAUDE.md` links to it) |
+| `CONTRIBUTING.md` | How to file issues and pull requests, porting rules, merging |
+| `SECURITY.md` | How to report a security problem, the trust model, and the rules held hard |
+| `LICENSE` | MIT licence |
+| `docs/DATA_MODEL.md` | The PostgreSQL records, the rules the database holds, and how to change the schema |
+| `docs/RELEASING.md` | Versions and channels, the release workflows, how to cut and roll back a release, and the one-time setup |
+| `docs/SELF_HOSTING.md` | Running a Flow release with Docker, Node or Replit, the update notice, and Clerk sign-in |
+| `docs/REPLIT.md` | A Replit workspace of this repository that follows a release channel (`FLOW_DEPLOY_REF`) |
+| `server/integrations/port.js` | The integration port every adapter implements |
+
+## Getting started
+
+Requirements: Node 24, npm and PostgreSQL 16 or later.
+
+```bash
+npm ci
+FLOW_TEST_DATABASE_URL=postgres://… npm test   # a throwaway database
+DATABASE_URL=postgres://… npm start             # http://localhost:19300/health
+```

package/SECURITY.md

@@ -0,0 +1,61 @@
+# Security Policy
+
+Flow handles a lab's invoices, supplier bills, bank details and integration
+credentials, and it can see case references from a dental lab. Treat every
+report about those with care.
+
+## Report a Security Issue
+
+Report privately through GitHub's "Report a vulnerability" (Security tab of
+this repository). Never open a public issue for a security problem, and never
+paste a credential, in full or in part.
+
+### What We Need
+
+- The affected version or commit, and the route, screen or file.
+- Steps to reproduce, with synthetic data only.
+- What an attacker gains.
+
+## Trust Model
+
+- **One installation per lab.** Each installation runs with its own database,
+  configuration and secrets. Installations never share data or credentials.
+- **People.** People sign in with Clerk. Flow's PostgreSQL holds each person's
+  role (`owner`, `admin` or `staff`) and access. A Clerk account with no Flow
+  role gets no access, and an installation is invitation only by default.
+  Owner-only actions need a verified owner sign-in (`docs/SELF_HOSTING.md`,
+  "Sign-in (Clerk)").
+- **Machine access.** The Flow API uses signed connector keys, never Clerk
+  sessions. Keys are read only from request headers and are checked against
+  the holder's current access on every use.
+- **Integrations.** Seazona, Xero and every later adapter reach the core only
+  through the integration port. Their credentials are stored per
+  organisation, encrypted, and are write-only in Settings.
+- **Issued documents are records.** An invoice a customer has been sent is
+  never changed in place; a change produces a new version.
+
+## Rules Held Hard
+
+- Never commit customer data, patient data, credentials, raw private messages
+  or runtime state. Tests and demos use synthetic fixtures. A photo, export or
+  screenshot from a real lab is customer data.
+- Never commit a real organisation identifier (a Xero tenant id, a Seazona
+  tenant hostname, an ABN or a bank account). They belong in the
+  installation's configuration.
+- Secrets live in the installation's secret store (for example Replit
+  Secrets), never in the repository, a log, an issue or a pull request. Name
+  the variable, never its value.
+- No account has a built-in or fallback password, in any environment.
+- Sign-in, API and integration routes are rate limited.
+- Session cookies are `Secure`, `HttpOnly` and `SameSite`.
+- Flow stores no clinical notes, images or scans, and keeps a patient
+  reference only where an invoice must print one.
+- CI runs gitleaks on every push and pull request
+  (`.github/workflows/secret-scan.yml`).
+
+## Out of Scope
+
+- Vulnerabilities in a third-party service Flow connects to (Clerk, Seazona,
+  Xero). Report those to the vendor.
+- Problems that need an attacker who already holds an owner sign-in or the
+  installation's secrets.

package/VISION.md

@@ -0,0 +1,65 @@
+# Flow — Vision
+
+Flow is invoicing, bill entry and a financial dashboard for a lab that makes
+work to order, first for dental labs.
+
+It is for the person who bills the work and pays the suppliers. Finished feels
+like this: completed cases become invoices they check and send, supplier bills
+go in once and get approved, and one dashboard shows cash, what is owed to the
+lab, what the lab owes, and the GST for the BAS period. Every invoice a
+customer was sent can be found again, exactly as it was sent.
+
+Flow is open source so any lab can run its own installation.
+
+## The core and its integrations
+
+The core is invoices, bills, payments, contacts, the price list and the
+dashboard. It works with no integration connected.
+
+Everything outside the core is an integration behind one contract (the
+integration port):
+
+- **Seazona** is the lab's case system. Its adapter is bundled: it ships in
+  the package and is on in the dental preset, and an owner can turn it off.
+  It turns completed cases into draft invoices through the Seazona API.
+- **Xero** is optional. Its adapter sends issued invoices and approved bills
+  to the owner's own Xero organisation and reads payments back.
+
+Adding an integration never changes the core.
+
+## Standing decisions
+
+### Why does Flow keep its own records?
+
+Flow is the store of record for the invoices and bills it issues. Xero gets a
+copy and owns bank reconciliation. A lab without Xero still has complete,
+correct records.
+
+### Why is a sent invoice never changed?
+
+What a customer was sent is a commercial commitment. A change makes a new
+version; the sent one stays as it was, attributed to whoever sent it.
+
+### Why does Flow keep as little patient data as it can?
+
+Dental cases carry health information, which Australian privacy law treats as
+sensitive. Flow keeps the case number and the practice. It keeps a patient
+reference only when a practice needs one printed on its invoice, and it keeps
+no clinical notes or images.
+
+### Why does each lab get its own installation?
+
+Labs' customers, prices and credentials must never meet. Each installation has
+its own data, configuration and secrets.
+
+## Out of scope
+
+- Case management, production tracking and scheduling. The case system owns
+  the case.
+- Patient records, clinical notes, scans and images.
+- Acting as the general ledger. Accounting software owns the ledger and the
+  bank feed.
+- Browser automation of another product. Integrations use published APIs.
+
+This is a guardrail, not a law of physics. Strong evidence can change it;
+record the change in the pull request that edits this file.