@foundrynorth/flux-schema

Canonical Drizzle ORM schema for the Foundry Flux database. This package is the shared source of truth for flux_* tables consumed by fn-flux and fn-v2.

What This Repo Owns

• TypeScript schema definitions in src/schema.ts
• Package exports in src/index.ts
• Published npm package: @foundrynorth/flux-schema

This repo does not own database rollout. It defines schema shape, but it does not apply schema changes directly.

Safety Rails

• The target database (broad-firefly-00588697) is shared with other apps.
• All Flux tables must stay flux_* prefixed.
• Do not run drizzle-kit push, drizzle-kit push --force, or any migration command from this repo.
• fn-flux is the only repo allowed to apply Flux schema changes to the shared database.

If a change adds or modifies tables, columns, indexes, enums, or constraints, the rollout happens later from fn-flux after this package has been published and updated there.

Local Setup

Option A: Devcontainer

This repo includes a minimal .devcontainer/devcontainer.json that installs Node 20 and runs npm ci. No Docker Compose services or local databases are required.

Option B: Local Node

Use the pinned Node version from .nvmrc:

nvm use
npm ci

If you do not use nvm, install Node 20 manually and then run npm ci.

Day-To-Day Commands

npm run check
npm run build

• npm run check runs TypeScript without emitting files.
• npm run build compiles src/ to dist/.

There are no local services to boot and no database credentials required for routine package work.

Contributor Workflow

1. Edit the schema in src/schema.ts.

2. If you add new exports, update src/index.ts.

3. Run:

   npm run check
   npm run build

4. Sanity-check the change with the consumer that needs it before publishing if the change is high impact.

For support engineers: if you are unsure whether a change affects database rollout, assume it does and hand off the actual push step to the fn-flux owner.

Release Workflow

1. Confirm the working tree is clean enough to release and that npm run check and npm run build both pass.

2. Bump the package version:

   npm version patch

   Use minor or major when the change calls for it.

3. Publish the package:

   npm publish

   npm publish runs prepublishOnly, which rebuilds the package.

4. Update consumers to the published version:

   cd ~/Developer/fn-flux
   pnpm install @foundrynorth/flux-schema@latest

   cd ~/Developer/fn-v2
   pnpm install @foundrynorth/flux-schema@latest

5. If the release changes database shape, apply the rollout from fn-flux only using that repo's vetted database workflow (pnpm db:generate, pnpm db:migrate:flux, and pnpm db:drift there, never here).

Consumer Usage

import {
  fluxProjects,
  fluxFulfillmentTickets,
  fluxActivityItems,
} from "@foundrynorth/flux-schema";

This package expects drizzle-orm >=0.45.0 as a peer dependency in consuming apps.

Consumers

• fn-flux - migration authority and primary app
• fn-v2 - shared read/write consumer

Further Reading

See:

• fn-docs: Shared Packages
• fn-docs: Shared Package Workflow