@tangle-network/starter-foundry 0.5.3 → 0.7.0

package/registry/layers/framework/expo-rn-rich/files/RootNavigator.tsx

@@ -0,0 +1,37 @@
+// Native stack at the root, bottom tabs nested inside the first
+// screen. This is the canonical two-level nav pattern — deep linking
+// resolves cleanly and transitions stay native.
+
+import { createNativeStackNavigator } from "@react-navigation/native-stack";
+import { createBottomTabNavigator } from "@react-navigation/bottom-tabs";
+import HomeScreen from "../screens/HomeScreen";
+import CanvasScreen from "../screens/CanvasScreen";
+
+export type RootStackParamList = {
+  MainTabs: undefined;
+};
+
+export type MainTabParamList = {
+  Home: undefined;
+  Canvas: undefined;
+};
+
+const Stack = createNativeStackNavigator<RootStackParamList>();
+const Tabs = createBottomTabNavigator<MainTabParamList>();
+
+function MainTabs() {
+  return (
+    <Tabs.Navigator screenOptions={{ headerShown: true }}>
+      <Tabs.Screen name="Home" component={HomeScreen} />
+      <Tabs.Screen name="Canvas" component={CanvasScreen} />
+    </Tabs.Navigator>
+  );
+}
+
+export default function RootNavigator() {
+  return (
+    <Stack.Navigator screenOptions={{ headerShown: false }}>
+      <Stack.Screen name="MainTabs" component={MainTabs} />
+    </Stack.Navigator>
+  );
+}

package/registry/layers/framework/expo-rn-rich/files/app.json

@@ -0,0 +1,27 @@
+{
+  "expo": {
+    "name": "{{projectName}}",
+    "slug": "{{packageName}}",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "userInterfaceStyle": "automatic",
+    "newArchEnabled": true,
+    "ios": {
+      "supportsTablet": true,
+      "bundleIdentifier": "com.starterfoundry.{{packageName}}"
+    },
+    "android": {
+      "package": "com.starterfoundry.{{packageName}}",
+      "useLegacyPackaging": true
+    },
+    "plugins": [
+      [
+        "expo-build-properties",
+        {
+          "ios": { "newArchEnabled": true },
+          "android": { "newArchEnabled": true }
+        }
+      ]
+    ]
+  }
+}

package/registry/layers/framework/expo-rn-rich/files/babel.config.js

@@ -0,0 +1,10 @@
+// IMPORTANT: react-native-reanimated/plugin MUST be the LAST plugin in
+// this list. Misordering produces "Reanimated 2 failed to create a
+// worklet" at runtime with no indication that babel was the cause.
+export default function (api) {
+  api.cache(true);
+  return {
+    presets: ["babel-preset-expo"],
+    plugins: ["react-native-reanimated/plugin"],
+  };
+}

package/registry/layers/framework/expo-rn-rich/files/metro.config.cjs

@@ -0,0 +1,9 @@
+const { getDefaultConfig } = require("expo/metro-config");
+
+const config = getDefaultConfig(__dirname);
+
+config.resolver.assetExts = Array.from(
+  new Set([...(config.resolver.assetExts ?? []), "wasm", "ttf"]),
+);
+
+module.exports = config;

package/registry/layers/framework/expo-rn-rich/files/metro.config.js

@@ -0,0 +1,14 @@
+// Skia ships a .wasm asset for its CanvasKit fallback on some
+// environments; register the extension so Metro doesn't skip it.
+import { getDefaultConfig } from "expo/metro-config";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const config = getDefaultConfig(__dirname);
+
+config.resolver.assetExts = Array.from(
+  new Set([...config.resolver.assetExts, "wasm", "ttf"]),
+);
+
+export default config;

package/registry/layers/framework/expo-rn-rich/files/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true,
+    "jsx": "react-jsx",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["App.tsx", "src/**/*"]
+}

package/registry/layers/framework/expo-rn-rich/manifest.json

@@ -0,0 +1,101 @@
+{
+  "id": "expo-rn-rich",
+  "description": "Expo React Native scaffold with Skia GPU canvas, Reanimated v3 worklets, Gesture Handler, and React Navigation (native stack + bottom tabs). Requires a custom dev client — Expo Go is incompatible with Skia and Reanimated v3.",
+  "appliesTo": ["expo-rn-rich"],
+  "files": [
+    { "source": "files/App.tsx", "target": "App.tsx" },
+    { "source": "files/app.json", "target": "app.json" },
+    { "source": "files/babel.config.js", "target": "babel.config.js" },
+    { "source": "files/metro.config.cjs", "target": "metro.config.cjs" },
+    { "source": "files/tsconfig.json", "target": "tsconfig.json" },
+    { "source": "files/RootNavigator.tsx", "target": "src/navigation/RootNavigator.tsx" },
+    { "source": "files/HomeScreen.tsx", "target": "src/screens/HomeScreen.tsx" },
+    { "source": "files/CanvasScreen.tsx", "target": "src/screens/CanvasScreen.tsx" }
+  ],
+  "packageDeps": {
+    "dependencies": {
+      "@react-navigation/bottom-tabs": "^7.2.0",
+      "@react-navigation/native": "^7.0.0",
+      "@react-navigation/native-stack": "^7.2.0",
+      "@shopify/react-native-skia": "^1.7.0",
+      "expo": "~52.0.0",
+      "expo-build-properties": "~0.13.0",
+      "expo-status-bar": "~2.0.0",
+      "react": "^19.2.0",
+      "react-native": "^0.79.0",
+      "react-native-gesture-handler": "~2.20.0",
+      "react-native-reanimated": "~3.16.0",
+      "react-native-safe-area-context": "~4.12.0",
+      "react-native-screens": "~4.1.0"
+    },
+    "devDependencies": {
+      "@babel/core": "^7.25.0",
+      "@types/react": "^19.2.0",
+      "typescript": "^5.9.0"
+    }
+  },
+  "buildHints": {
+    "whenToUse": "Pick expo-rn-rich when the app needs GPU-backed 2D drawing (Skia), worklet-driven 60fps animations (Reanimated v3), native gesture composition (Gesture Handler), and stack+tab navigation (React Navigation). If the user just needs a plain React Native shell without the animation stack, use expo-react-native-ts — this family pulls in ~15MB of extra native deps that need a dev client build.",
+    "firstSteps": [
+      "Run `pnpm install` to install all JS dependencies — no native build required at this step.",
+      "Run `npx tsc --noEmit` to verify that all types compile cleanly against the installed packages.",
+      "Run `expo prebuild --clean` to generate the ios/ and android/ native project folders from app.json config.",
+      "Build a custom dev client with `eas build --profile development` or `expo run:ios` / `expo run:android` — Expo Go cannot load Skia or Reanimated v3 native modules.",
+      "Once the dev client is installed on device/simulator, start the bundler with `npx expo start --dev-client` and open it in the custom client app.",
+      "Replace {{headline}} / {{subheadline}} in HomeScreen.tsx with real copy, or let the compose tool substitute them via the defaults in the family manifest."
+    ],
+    "gotchas": [
+      "Expo Go INCOMPATIBILITY: Skia + Reanimated v3 require a custom dev client. Users who run `npx expo start` and scan the QR with Expo Go will see 'Native module RNReanimated is not installed'.",
+      "Reanimated babel plugin order: `react-native-reanimated/plugin` MUST be the LAST entry in the babel.config.js plugins array. Misordering silently breaks worklets with a 'Reanimated 2 failed to create a worklet' runtime error.",
+      "`react-native-gesture-handler` must be imported at the TOP of App.tsx before any other imports — any import before it initialises without the gesture patches applied and fires warnings in production.",
+      "GestureHandlerRootView must wrap the entire app tree in App.tsx, not just individual screens, or nested gestures drop events on Android.",
+      "expo-build-properties is required as a dependency because it is referenced as an Expo config plugin in app.json → plugins. Missing it causes `expo prebuild` to fail with 'Cannot find module expo-build-properties'.",
+      "Android: The `android.useLegacyPackaging: true` flag in app.json is needed for Hermes-compatible Reanimated — without it the APK balloons by ~20MB.",
+      "Worklet constraints: code inside `useAnimatedStyle` / `useAnimatedReaction` runs on the UI thread and cannot close over JS-thread variables unless marked with `'worklet'`. Mis-use shows up as 'ReferenceError: X is not defined' on interaction.",
+      "EAS Build: Reanimated + Skia push the build past Expo's free-tier 45-minute limit on first run — set `cache.key` in eas.json to cache native pods, or upgrade to a paid tier."
+    ],
+    "architectureNotes": [
+      "Reanimated v3 requires its Babel plugin to be the LAST plugin in babel.config.js — misordering silently breaks worklets.",
+      "GestureHandlerRootView MUST wrap the entire app tree (App.tsx), not individual screens, or nested gestures drop events on Android.",
+      "@shopify/react-native-skia ships its own native module — it will NOT run inside Expo Go. The project requires a dev client (`eas build --profile development`) or `expo prebuild` to generate ios/android folders.",
+      "react-native-screens is enabled via `enableScreens()` before any navigator renders — this yields 30–40% lower memory on large stacks.",
+      "Screens live under src/screens/, navigators under src/navigation/. This split lets agents add screens without rewriting the root navigator."
+    ],
+    "placeholders": [
+      {
+        "path": "src/screens/HomeScreen.tsx",
+        "description": "{{headline}} and {{subheadline}} are template vars substituted at compose time. The three Section cards (Navigation, Auth, Payments) are stubs — replace or extend with real app content."
+      },
+      {
+        "path": "src/screens/CanvasScreen.tsx",
+        "description": "Orbiting circle driven by Reanimated shared values + Skia Canvas. Replace the Circle/Path primitives with your GPU-backed UI — keep the Canvas, GestureDetector, and shared-value scaffolding."
+      },
+      {
+        "path": "app.json",
+        "description": "{{projectName}} and {{packageName}} are substituted at compose time. Update ios.bundleIdentifier and android.package to match your real bundle ID before running eas build."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "pnpm install",
+      "npx tsc --noEmit",
+      "expo prebuild --clean",
+      "npx expo start --dev-client",
+      "eas build --profile development",
+      "node validate-expo-rn-rich.mjs"
+    ],
+    "entrypoints": [
+      "App.tsx",
+      "src/navigation/RootNavigator.tsx",
+      "src/screens/HomeScreen.tsx",
+      "src/screens/CanvasScreen.tsx"
+    ],
+    "preview": null,
+    "extensionPoints": [
+      "src/screens/",
+      "src/navigation/RootNavigator.tsx",
+      "app.json"
+    ]
+  }
+}

package/registry/layers/framework/fintech-ledger-backend/files/db.ts

@@ -0,0 +1,10 @@
+import postgres from 'postgres'
+import { drizzle } from 'drizzle-orm/postgres-js'
+import * as schema from './schema.js'
+
+// ── env ──────────────────────────────────────────────────────────────────────
+const DATABASE_URL: string = process.env['DATABASE_URL'] ?? 'postgres://localhost:5432/ledger'
+// ─────────────────────────────────────────────────────────────────────────────
+
+const client = postgres(DATABASE_URL, { ssl: 'prefer', max: 10 })
+export const db = drizzle(client, { schema })

package/registry/layers/framework/fintech-ledger-backend/files/drizzle.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  schema: './src/db/schema.ts',
+  out: './drizzle',
+  dialect: 'postgresql',
+  dbCredentials: { url: process.env.DATABASE_URL ?? 'postgres://localhost:5432/ledger' },
+  strict: true,
+})

package/registry/layers/framework/fintech-ledger-backend/files/ledger/query.ts

@@ -0,0 +1,66 @@
+import { Decimal } from 'decimal.js'
+import { and, desc, eq, gte, lte } from 'drizzle-orm'
+import { db } from '../db/client.js'
+import { entries, transactions } from '../db/schema.js'
+
+export interface LedgerBalance {
+  accountId: string
+  balance: string
+  asOf: string
+}
+
+export interface LedgerEntry {
+  id: string
+  transactionId: string
+  accountId: string
+  direction: 'debit' | 'credit'
+  amount: string
+  currency: string
+  postedAt: Date
+}
+
+export async function accountBalance(accountId: string, asOf: Date = new Date()): Promise<LedgerBalance> {
+  const rows = await db
+    .select({
+      direction: entries.direction,
+      amount: entries.amount,
+    })
+    .from(entries)
+    .innerJoin(transactions, eq(entries.transactionId, transactions.id))
+    .where(and(eq(entries.accountId, accountId), lte(transactions.postedAt, asOf)))
+
+  const balance = rows.reduce<Decimal>((acc, r) => {
+    const amt = new Decimal(r.amount)
+    return r.direction === 'credit' ? acc.plus(amt) : acc.minus(amt)
+  }, new Decimal(0))
+
+  return { accountId, balance: balance.toFixed(2), asOf: asOf.toISOString() }
+}
+
+export async function accountEntries(
+  accountId: string,
+  options: { limit?: number; from?: Date; to?: Date } = {},
+): Promise<LedgerEntry[]> {
+  const limit = options.limit ?? 100
+  const conditions = [eq(entries.accountId, accountId)]
+  if (options.from) conditions.push(gte(transactions.postedAt, options.from))
+  if (options.to) conditions.push(lte(transactions.postedAt, options.to))
+
+  const rows = await db
+    .select({
+      id: entries.id,
+      transactionId: entries.transactionId,
+      accountId: entries.accountId,
+      direction: entries.direction,
+      amount: entries.amount,
+      currency: entries.currency,
+      postedAt: transactions.postedAt,
+    })
+    .from(entries)
+    .innerJoin(transactions, eq(entries.transactionId, transactions.id))
+    .where(and(...conditions))
+    .orderBy(desc(transactions.postedAt))
+    .limit(limit)
+
+  return rows
+}

package/registry/layers/framework/fintech-ledger-backend/files/money.ts

@@ -0,0 +1,32 @@
+import Decimal from 'decimal.js'
+
+// Money always flows through Decimal. Everywhere a numeric string enters
+// from the outside world, it goes through `m(...)`. Everywhere it leaves,
+// it's `.toFixed(4)` so NUMERIC storage is byte-stable.
+Decimal.set({ precision: 40, rounding: Decimal.ROUND_HALF_EVEN })
+
+export function m(raw: string | number | Decimal): Decimal {
+  if (raw instanceof Decimal) return raw
+  if (typeof raw === 'number') {
+    if (!Number.isFinite(raw)) throw new Error('invalid amount (non-finite)')
+    // Funnel through string to avoid IEEE-754 artifacts from float->Decimal.
+    return new Decimal(raw.toString())
+  }
+  if (typeof raw === 'string') {
+    if (!/^-?\d+(\.\d+)?$/.test(raw)) throw new Error(`invalid amount string: ${raw}`)
+    return new Decimal(raw)
+  }
+  throw new Error('unsupported amount type')
+}
+
+export function sum(values: Iterable<Decimal>): Decimal {
+  let total = new Decimal(0)
+  for (const v of values) total = total.plus(v)
+  return total
+}
+
+export function toDbString(value: Decimal): string {
+  // 4 scale matches the NUMERIC(20,4) column. HALF_EVEN (banker's rounding)
+  // minimizes drift under repeated rounding.
+  return value.toFixed(4, Decimal.ROUND_HALF_EVEN)
+}

package/registry/layers/framework/fintech-ledger-backend/files/post.ts

@@ -0,0 +1,141 @@
+// Atomic post_transaction: validates the debit=credit invariant per currency
+// and inserts the transaction + entries in a single DB transaction. Any
+// error rolls the whole thing back so the ledger can never land unbalanced.
+import { eq } from 'drizzle-orm'
+import { db } from '../db/client.js'
+import { entries, transactions, type Entry, type Transaction } from '../db/schema.js'
+import { m, toDbString } from './money.js'
+import Decimal from 'decimal.js'
+
+export interface PostEntryInput {
+  accountId: string
+  direction: 'debit' | 'credit'
+  amount: string | number
+  currency: string
+}
+
+export interface PostTransactionInput {
+  idempotencyKey?: string
+  externalRef?: string
+  memo?: string
+  postedAt?: Date
+  entries: PostEntryInput[]
+}
+
+export interface PostResult {
+  transaction: Transaction
+  entries: Entry[]
+  idempotent: boolean
+}
+
+export class LedgerError extends Error {
+  constructor(message: string, public readonly code: string) {
+    super(message)
+  }
+}
+
+export async function postTransaction(input: PostTransactionInput): Promise<PostResult> {
+  if (input.entries.length < 2) {
+    throw new LedgerError('a transaction needs at least two entries', 'NOT_ENOUGH_ENTRIES')
+  }
+
+  // Group by currency; each currency group must balance debits == credits.
+  const byCurrency = new Map<string, { debit: Decimal; credit: Decimal }>()
+  for (const e of input.entries) {
+    if (!/^[A-Z]{3}$/.test(e.currency)) {
+      throw new LedgerError(`bad currency code: ${e.currency}`, 'BAD_CURRENCY')
+    }
+    const amount = m(e.amount)
+    if (amount.isNegative() || amount.isZero()) {
+      throw new LedgerError('entry amount must be positive', 'BAD_AMOUNT')
+    }
+    const bucket = byCurrency.get(e.currency) ?? { debit: new Decimal(0), credit: new Decimal(0) }
+    if (e.direction === 'debit') bucket.debit = bucket.debit.plus(amount)
+    else bucket.credit = bucket.credit.plus(amount)
+    byCurrency.set(e.currency, bucket)
+  }
+
+  for (const [ccy, { debit, credit }] of byCurrency) {
+    if (!debit.equals(credit)) {
+      throw new LedgerError(
+        `unbalanced ${ccy}: debits=${debit.toFixed(4)} credits=${credit.toFixed(4)}`,
+        'UNBALANCED',
+      )
+    }
+  }
+
+  return db.transaction(async (tx) => {
+    // Idempotency: if the key already exists, return the existing transaction.
+    if (input.idempotencyKey) {
+      const existing = await tx
+        .select()
+        .from(transactions)
+        .where(eq(transactions.idempotencyKey, input.idempotencyKey))
+        .limit(1)
+      const txn = existing[0]
+      if (txn) {
+        const rows = await tx.select().from(entries).where(eq(entries.transactionId, txn.id))
+        return { transaction: txn, entries: rows, idempotent: true }
+      }
+    }
+
+    const [txnRow] = await tx
+      .insert(transactions)
+      .values({
+        idempotencyKey: input.idempotencyKey ?? null,
+        externalRef: input.externalRef ?? null,
+        memo: input.memo ?? null,
+        postedAt: input.postedAt ?? new Date(),
+      })
+      .returning()
+    if (!txnRow) throw new LedgerError('insert returned no rows', 'INSERT_FAILED')
+
+    const entryRows = await tx
+      .insert(entries)
+      .values(
+        input.entries.map((e) => ({
+          transactionId: txnRow.id,
+          accountId: e.accountId,
+          direction: e.direction,
+          amount: toDbString(m(e.amount)),
+          currency: e.currency,
+          postedAt: input.postedAt ?? new Date(),
+        })),
+      )
+      .returning()
+
+    // Defense-in-depth: re-check balance after insert in case a trigger
+    // altered anything. Cheap and protects against silent corruption.
+    const postedByCcy = new Map<string, Decimal>()
+    for (const row of entryRows) {
+      const signed = row.direction === 'debit' ? m(row.amount) : m(row.amount).negated()
+      postedByCcy.set(row.currency, (postedByCcy.get(row.currency) ?? new Decimal(0)).plus(signed))
+    }
+    for (const [ccy, net] of postedByCcy) {
+      if (!net.isZero()) {
+        throw new LedgerError(`post-insert invariant violated: ${ccy} net=${net.toFixed(4)}`, 'INVARIANT')
+      }
+    }
+
+    return { transaction: txnRow, entries: entryRows, idempotent: false }
+  })
+}
+
+/** Convenience: a two-entry transfer. Not a replacement for postTransaction — use it for tests & trivial cases only. */
+export async function postTransfer(params: {
+  fromAccountId: string
+  toAccountId: string
+  amount: string | number
+  currency: string
+  memo?: string
+  idempotencyKey?: string
+}): Promise<PostResult> {
+  return postTransaction({
+    idempotencyKey: params.idempotencyKey,
+    memo: params.memo,
+    entries: [
+      { accountId: params.fromAccountId, direction: 'credit', amount: params.amount, currency: params.currency },
+      { accountId: params.toAccountId, direction: 'debit', amount: params.amount, currency: params.currency },
+    ],
+  })
+}

package/registry/layers/framework/fintech-ledger-backend/files/schema.ts

@@ -0,0 +1,87 @@
+// Double-entry ledger schema. Every transaction is N entries; sum of debits
+// MUST equal sum of credits per currency. Amounts are NUMERIC(20,4) — never
+// float. See src/ledger/post.ts for the posting invariant.
+import { pgTable, uuid, varchar, timestamp, numeric, text, index, uniqueIndex, pgEnum } from 'drizzle-orm/pg-core'
+import { relations } from 'drizzle-orm'
+
+export const accountTypeEnum = pgEnum('account_type', [
+  'asset',
+  'liability',
+  'equity',
+  'income',
+  'expense',
+])
+
+export const entryDirectionEnum = pgEnum('entry_direction', ['debit', 'credit'])
+
+export const accounts = pgTable(
+  'accounts',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    // Human-readable code for the chart of accounts, e.g. "1000" (cash), "4000" (revenue).
+    code: varchar('code', { length: 32 }).notNull(),
+    name: varchar('name', { length: 200 }).notNull(),
+    type: accountTypeEnum('type').notNull(),
+    // ISO 4217 currency code. Multi-currency accounts use a separate account per currency.
+    currency: varchar('currency', { length: 3 }).notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    codeCurrencyUnique: uniqueIndex('accounts_code_currency_uniq').on(t.code, t.currency),
+  }),
+)
+
+export const transactions = pgTable(
+  'transactions',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    externalRef: varchar('external_ref', { length: 200 }),
+    // Idempotency key — retried requests with the same key return the existing txn.
+    idempotencyKey: varchar('idempotency_key', { length: 128 }),
+    memo: text('memo'),
+    postedAt: timestamp('posted_at', { withTimezone: true }).notNull().defaultNow(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    idempotencyUniq: uniqueIndex('transactions_idempotency_uniq').on(t.idempotencyKey),
+    externalRefIdx: index('transactions_external_ref_idx').on(t.externalRef),
+    postedAtIdx: index('transactions_posted_at_idx').on(t.postedAt),
+  }),
+)
+
+export const entries = pgTable(
+  'entries',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    transactionId: uuid('transaction_id')
+      .notNull()
+      .references(() => transactions.id, { onDelete: 'restrict' }),
+    accountId: uuid('account_id')
+      .notNull()
+      .references(() => accounts.id, { onDelete: 'restrict' }),
+    direction: entryDirectionEnum('direction').notNull(),
+    // NUMERIC(20,4): 20 total digits, 4 after the decimal. Handles >99 trillion USD with 4-dp precision.
+    amount: numeric('amount', { precision: 20, scale: 4 }).notNull(),
+    currency: varchar('currency', { length: 3 }).notNull(),
+    postedAt: timestamp('posted_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    accountPostedIdx: index('entries_account_posted_idx').on(t.accountId, t.postedAt),
+    transactionIdx: index('entries_transaction_idx').on(t.transactionId),
+  }),
+)
+
+export const transactionsRelations = relations(transactions, ({ many }) => ({
+  entries: many(entries),
+}))
+
+export const entriesRelations = relations(entries, ({ one }) => ({
+  transaction: one(transactions, { fields: [entries.transactionId], references: [transactions.id] }),
+  account: one(accounts, { fields: [entries.accountId], references: [accounts.id] }),
+}))
+
+export type Account = typeof accounts.$inferSelect
+export type NewAccount = typeof accounts.$inferInsert
+export type Transaction = typeof transactions.$inferSelect
+export type Entry = typeof entries.$inferSelect
+export type NewEntry = typeof entries.$inferInsert

package/registry/layers/framework/fintech-ledger-backend/files/server.ts

@@ -0,0 +1,26 @@
+import Fastify from 'fastify'
+import { transactionsPlugin } from './api/transactions.js'
+
+// ── env ──────────────────────────────────────────────────────────────────────
+const PORT: number = parseInt(process.env['PORT'] ?? '3000', 10)
+const HOST: string = process.env['HOST'] ?? '0.0.0.0'
+const DATABASE_URL: string = process.env['DATABASE_URL'] ?? 'postgres://localhost:5432/ledger'
+const BASE_CURRENCY: string = process.env['BASE_CURRENCY'] ?? 'USD'
+// ─────────────────────────────────────────────────────────────────────────────
+
+const server = Fastify({ logger: true })
+
+server.get('/health', async () => ({
+  status: 'ok',
+  service: 'starter-foundry-ledger',
+  baseCurrency: BASE_CURRENCY,
+}))
+
+await server.register(transactionsPlugin)
+
+server.log.info(
+  { port: PORT, host: HOST, db: DATABASE_URL.replace(/:[^:@]+@/, ':***@'), currency: BASE_CURRENCY },
+  'starter-foundry-ledger starting',
+)
+
+await server.listen({ port: PORT, host: HOST })

package/registry/layers/framework/fintech-ledger-backend/files/transactions-api.ts

@@ -0,0 +1,59 @@
+import type { FastifyPluginAsync } from 'fastify'
+import { LedgerError, postTransaction } from '../ledger/post.js'
+import { accountBalance, accountEntries } from '../ledger/query.js'
+
+interface PostTransactionBody {
+  idempotencyKey?: string
+  externalRef?: string
+  memo?: string
+  entries?: Array<{
+    accountId: string
+    direction: 'debit' | 'credit'
+    amount: string | number
+    currency: string
+  }>
+}
+
+export const transactionsPlugin: FastifyPluginAsync = async (app) => {
+  app.post<{ Body: PostTransactionBody }>('/api/transactions', async (req, reply) => {
+    const body = req.body
+    if (!body?.entries || body.entries.length === 0) {
+      return reply.code(422).send({ error: 'entries[] required' })
+    }
+    try {
+      const result = await postTransaction({
+        idempotencyKey: body.idempotencyKey,
+        externalRef: body.externalRef,
+        memo: body.memo,
+        entries: body.entries,
+      })
+      return reply.code(result.idempotent ? 200 : 201).send(result)
+    } catch (err) {
+      if (err instanceof LedgerError) {
+        return reply.code(422).send({ error: err.message, code: err.code })
+      }
+      throw err
+    }
+  })
+
+  app.get<{ Params: { id: string }; Querystring: { asOf?: string } }>(
+    '/api/accounts/:id/balance',
+    async (req, reply) => {
+      const asOfRaw = req.query.asOf
+      const asOf = asOfRaw ? new Date(asOfRaw) : new Date()
+      if (Number.isNaN(asOf.getTime())) {
+        return reply.code(400).send({ error: 'invalid asOf timestamp' })
+      }
+      return accountBalance(req.params.id, asOf)
+    },
+  )
+
+  app.get<{ Params: { id: string }; Querystring: { limit?: string } }>(
+    '/api/accounts/:id/entries',
+    async (req, reply) => {
+      const limit = Math.min(parseInt(req.query.limit ?? '100', 10) || 100, 500)
+      const rows = await accountEntries(req.params.id, { limit })
+      return { entries: rows }
+    },
+  )
+}