@tangle-network/starter-foundry 0.5.4 → 0.7.2

package/registry/layers/framework/kotlin-multiplatform/files/pom.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <groupId>com.example</groupId>
+    <artifactId>my-kmp-app</artifactId>
+    <version>1.0-SNAPSHOT</version>
+    <packaging>jar</packaging>
+    <properties>
+        <kotlin.version>1.9.22</kotlin.version>
+        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.target>17</maven.compiler.target>
+    </properties>
+    <dependencies>
+        <dependency>
+            <groupId>org.jetbrains.kotlin</groupId>
+            <artifactId>kotlin-stdlib</artifactId>
+            <version>${kotlin.version}</version>
+        </dependency>
+    </dependencies>
+    <build>
+        <sourceDirectory>src/commonMain/kotlin</sourceDirectory>
+        <plugins>
+            <plugin>
+                <groupId>org.jetbrains.kotlin</groupId>
+                <artifactId>kotlin-maven-plugin</artifactId>
+                <version>${kotlin.version}</version>
+                <executions>
+                    <execution>
+                        <id>compile</id>
+                        <goals><goal>compile</goal></goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

package/registry/layers/framework/kotlin-multiplatform/files/settings.gradle.kts

@@ -0,0 +1,7 @@
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        mavenCentral()
+    }
+}
+rootProject.name = "my-kmp-app"

package/registry/layers/framework/kotlin-multiplatform/files/src/commonMain/kotlin/App.kt

@@ -0,0 +1,3 @@
+fun main() {
+    println("Hello from Kotlin Multiplatform!")
+}

package/registry/layers/framework/kotlin-multiplatform/manifest.json

@@ -0,0 +1,74 @@
+{
+  "id": "kotlin-multiplatform",
+  "description": "Kotlin Multiplatform framework layer — Gradle build, shared commonMain entry point, and expect/actual Platform surface for cross-platform targets.",
+  "appliesTo": ["kotlin-multiplatform"],
+  "files": [
+    {
+      "source": "files/settings.gradle.kts",
+      "target": "settings.gradle.kts"
+    },
+    {
+      "source": "files/build.gradle.kts",
+      "target": "build.gradle.kts"
+    },
+    {
+      "source": "files/src/commonMain/kotlin/App.kt",
+      "target": "src/commonMain/kotlin/App.kt"
+    },
+    {
+      "source": "files/AGENTS.md",
+      "target": "AGENTS.md"
+    }
+  ],
+  "buildHints": {
+    "whenToUse": "Pick kotlin-multiplatform when the user names KMP, Kotlin Multiplatform, Compose Multiplatform, expect/actual, or wants Jetpack Compose on iOS. For Flutter use flutter-app; for JS-driven mobile use expo-react-native-ts.",
+    "firstSteps": [
+      "Install JDK 17+ and ensure `java -version` reports 17 or higher.",
+      "Install Gradle 8+ (`brew install gradle` on macOS).",
+      "Run `gradle dependencies --no-daemon` to resolve and download dependencies.",
+      "Run `gradle build --no-daemon` to compile commonMain and produce outputs.",
+      "Open `src/commonMain/kotlin/App.kt` — this is the shared entry point."
+    ],
+    "gotchas": [
+      "Requires Gradle 8+ and JDK 17+ on PATH; invoke via `gradle <task> --no-daemon`.",
+      "iOS/Android native targets require the Kotlin Multiplatform Gradle plugin; this setup compiles the JVM/common target only.",
+      "Kotlin stdlib version must stay in sync with the kotlin(\"multiplatform\") plugin version in build.gradle.kts.",
+      "Do NOT re-enable `kotlin.native.binary.memoryModel=strict` — the new memory model (default since Kotlin 1.9) is required by coroutines and Compose Multiplatform.",
+      "`expect` declarations must be matched by an `actual` in EVERY target source set — missing an actual in iosMain fails the iOS build only."
+    ],
+    "architectureNotes": [
+      "`src/commonMain/kotlin/App.kt` exports `main()` — the minimal shared entry point. Extend commonMain with your cross-platform logic here.",
+      "Platform APIs go behind `expect fun platformName(): String` in commonMain with `actual` implementations in androidMain + iosMain (add those source sets as needed).",
+      "Auth/payments/sdk slot layers drop JSON config at the repo root; a bootstrap function in commonMain reads those and dispatches to the right platform service via expect/actual."
+    ],
+    "placeholders": [
+      {
+        "path": "settings.gradle.kts",
+        "description": "rootProject.name `my-kmp-app` — replace with your project slug (the rootProject.name directive)."
+      },
+      {
+        "path": "src/commonMain/kotlin/App.kt",
+        "description": "Package declaration — add `package com.example.starter` if needed; must match any platform actuals."
+      }
+    ]
+  },
+  "contextHints": {
+    "commands": [
+      "gradle dependencies --no-daemon",
+      "gradle build --no-daemon",
+      "gradle test --no-daemon",
+      "gradle tasks --no-daemon"
+    ],
+    "entrypoints": [
+      "src/commonMain/kotlin/App.kt",
+      "build.gradle.kts",
+      "settings.gradle.kts"
+    ],
+    "preview": null,
+    "extensionPoints": [
+      "src/commonMain/kotlin/",
+      "src/androidMain/kotlin/",
+      "src/iosMain/kotlin/"
+    ]
+  }
+}

package/registry/layers/framework/kyc-onboarding/manifest.json

@@ -0,0 +1,8 @@
+{
+  "id": "kyc-onboarding",
+  "description": "node framework layer for kyc-onboarding.",
+  "appliesTo": [
+    "kyc-onboarding"
+  ],
+  "files": []
+}

package/registry/layers/framework/legal-case-mgmt/files/.env.example

@@ -0,0 +1,5 @@
+# Required: Postgres 15+ connection string
+DATABASE_URL=postgres://user:password@localhost:5432/legal_db
+
+# Optional: override default port (8102)
+# PORT=8102

package/registry/layers/framework/legal-case-mgmt/files/AGENTS.md

@@ -0,0 +1,62 @@
+# Legal Case Management Scaffold
+
+Node.js HTTP API for legal practice management. Drizzle ORM + Postgres + decimal.js.
+
+## Setup
+
+```bash
+cp .env.example .env          # set DATABASE_URL
+pnpm install
+pnpm db:generate               # generate Drizzle migrations
+pnpm db:migrate                # apply migrations to Postgres
+pnpm dev                       # starts on port 8102
+curl http://localhost:8102/health
+```
+
+## REST API
+
+| Method | Path | Body / Notes |
+|--------|------|-------------|
+| GET | /health | Returns `{ status: "ok" }` |
+| POST | /api/matters | `{ clientId, matterNumber, title, practiceArea?, opposingParties? }` |
+| GET | /api/matters/:id | Returns matter + parties |
+| POST | /api/matters/:id/time-entries | `{ attorneyId, workedAt (ISO), minutes (integer), narrative, billable? }` |
+| GET | /api/matters/:id/time-entries | Lists unbilled billable entries |
+| POST | /api/matters/:id/invoice/draft | Drafts invoice from unbilled entries; requires billing_rates row for each attorney |
+
+## Key files
+
+| File | Purpose |
+|------|---------|
+| `src/db/schema.ts` | Drizzle table definitions — edit here to extend the data model |
+| `src/api/matter.ts` | Matter CRUD + time-entry endpoints |
+| `src/api/billing.ts` | Invoice draft generator (resolves historical rates, uses Decimal for cents) |
+| `src/db/client.ts` | Drizzle client — reads DATABASE_URL from env |
+| `drizzle.config.ts` | Drizzle Kit migration config |
+
+## Data model
+
+- **clients** — billing entity for a matter
+- **attorneys** — firm staff; each has time-bounded billing_rates rows
+- **matters** — unit of work (and privilege); status: open | closed | archived
+- **parties** — roles on a matter: client | opposing | witness | counsel | other
+- **documents** — content-addressed (sha256 hash), immutable rows
+- **billing_rates** — hourly_rate_cents + effectiveAt; resolved at time-of-work
+- **time_entries** — integer minutes, locked to an invoice once drafted
+- **invoices** — status: draft | sent | paid | void; totals in integer cents
+
+## Critical rules
+
+- Store time in **integer minutes** — never fractional hours
+- Store money in **integer cents** — billing.ts uses decimal.js for all arithmetic
+- **Never** add UPDATE/DELETE endpoints for the documents table (immutability is a retention requirement)
+- Access control must be at the **matter level** to protect attorney-client privilege
+- Conflicts check is **not implemented** — add before any production use
+- Trust / IOLTA funds must be in a **separate ledger** — do not commingle with operating funds
+
+## Extension points
+
+- Add new practice-area fields or matter subtypes in `src/db/schema.ts`
+- Add new API routes in `src/api/` and register them in `src/server.ts`
+- Add a `/api/clients` and `/api/attorneys` CRUD layer for onboarding
+- Add a conflicts-check middleware that queries parties before inserting a new matter

package/registry/layers/framework/legal-case-mgmt/files/billing.ts

@@ -0,0 +1,130 @@
+// Invoice draft generator. Aggregates unbilled time entries for a matter,
+// resolves the effective billing rate at each entry's workedAt, computes
+// totals in integer cents (via Decimal for rounding safety), and emits a
+// draft invoice + links the time entries to it in one DB transaction.
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { Decimal } from 'decimal.js'
+import { and, desc, eq, isNull, lte } from 'drizzle-orm'
+import { db } from '../db/client.ts'
+import { billingRates, invoices, matters, timeEntries } from '../db/schema.ts'
+
+Decimal.set({ precision: 40, rounding: 2 })
+
+async function resolveRate(attorneyId: string, at: Date): Promise<{ rateCents: number; currency: string }> {
+  const rows = await db
+    .select()
+    .from(billingRates)
+    .where(and(eq(billingRates.attorneyId, attorneyId), lte(billingRates.effectiveAt, at)))
+    .orderBy(desc(billingRates.effectiveAt))
+    .limit(1)
+  const r = rows[0]
+  if (!r) throw new Error(`no billing rate for attorney ${attorneyId} effective at ${at.toISOString()}`)
+  return { rateCents: r.hourlyRateCents, currency: r.currency }
+}
+
+export interface DraftInvoiceLine {
+  timeEntryId: string
+  minutes: number
+  rateCents: number
+  amountCents: number
+}
+
+export interface DraftInvoiceResult {
+  invoiceId: string
+  invoiceNumber: string
+  matterId: string
+  currency: string
+  subtotalCents: number
+  totalCents: number
+  lines: DraftInvoiceLine[]
+}
+
+/** Generate a draft invoice from every unbilled billable time entry on a matter. */
+export async function draftInvoice(matterId: string): Promise<DraftInvoiceResult> {
+  return db.transaction(async (tx) => {
+    const [matter] = await tx.select().from(matters).where(eq(matters.id, matterId)).limit(1)
+    if (!matter) throw new Error(`matter not found: ${matterId}`)
+
+    const unbilled = await tx
+      .select()
+      .from(timeEntries)
+      .where(
+        and(
+          eq(timeEntries.matterId, matterId),
+          eq(timeEntries.billable, true),
+          isNull(timeEntries.invoiceId),
+        ),
+      )
+    if (unbilled.length === 0) throw new Error('no unbilled time entries')
+
+    let subtotal = new Decimal(0)
+    let currency: string | null = null
+    const lines: DraftInvoiceLine[] = []
+    for (const entry of unbilled) {
+      const rate = await resolveRate(entry.attorneyId, entry.workedAt)
+      if (currency && currency !== rate.currency) {
+        throw new Error('multi-currency invoice not supported — split into per-currency invoices')
+      }
+      currency = rate.currency
+      // amount = rateCents * minutes / 60. Use Decimal so fractional cents round once at the end.
+      const amount = new Decimal(rate.rateCents).mul(entry.minutes).div(60)
+      const amountCents = Number(amount.toFixed(0, 2))
+      subtotal = subtotal.plus(amountCents)
+      lines.push({
+        timeEntryId: entry.id,
+        minutes: entry.minutes,
+        rateCents: rate.rateCents,
+        amountCents,
+      })
+    }
+
+    const invoiceNumber = `INV-${matter.matterNumber}-${Date.now()}`
+    const subtotalCents = Number(subtotal.toFixed(0))
+    const [invoice] = await tx
+      .insert(invoices)
+      .values({
+        matterId,
+        clientId: matter.clientId,
+        invoiceNumber,
+        status: 'draft',
+        subtotalCents,
+        totalCents: subtotalCents,
+        currency: currency!,
+      })
+      .returning()
+    if (!invoice) throw new Error('Invoice not found')
+
+    // Lock the time entries to this invoice so they can't be drafted twice.
+    for (const line of lines) {
+      await tx
+        .update(timeEntries)
+        .set({ invoiceId: invoice.id })
+        .where(eq(timeEntries.id, line.timeEntryId))
+    }
+
+    return {
+      invoiceId: invoice.id,
+      invoiceNumber,
+      matterId,
+      currency: currency!,
+      subtotalCents,
+      totalCents: subtotalCents,
+      lines,
+    }
+  })
+}
+
+export async function draftInvoiceRoute(
+  _request: IncomingMessage,
+  response: ServerResponse,
+  matterId: string,
+) {
+  try {
+    const result = await draftInvoice(matterId)
+    response.writeHead(201, { 'content-type': 'application/json' })
+    response.end(JSON.stringify(result))
+  } catch (err) {
+    response.writeHead(422, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: (err as Error).message }))
+  }
+}

package/registry/layers/framework/legal-case-mgmt/files/db.ts

@@ -0,0 +1,8 @@
+import postgres from 'postgres'
+import { drizzle } from 'drizzle-orm/postgres-js'
+import * as schema from './schema.ts'
+
+const url = process.env.DATABASE_URL
+if (!url) throw new Error('DATABASE_URL is required')
+const client = postgres(url, { ssl: 'prefer', max: 10 })
+export const db = drizzle(client, { schema })

package/registry/layers/framework/legal-case-mgmt/files/drizzle.config.ts

@@ -0,0 +1,9 @@
+import type { Config } from 'drizzle-kit'
+
+export default {
+  schema: './src/db/schema.ts',
+  out: './drizzle',
+  dialect: 'postgresql',
+  dbCredentials: { url: process.env.DATABASE_URL ?? '' },
+  strict: true,
+} satisfies Config

package/registry/layers/framework/legal-case-mgmt/files/matter.ts

@@ -0,0 +1,111 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { and, eq } from 'drizzle-orm'
+import { db } from '../db/client.ts'
+import { matters, parties, timeEntries } from '../db/schema.ts'
+
+async function readJsonBody(request: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = []
+  for await (const chunk of request) chunks.push(chunk as Buffer)
+  const raw = Buffer.concat(chunks).toString('utf8')
+  return raw ? JSON.parse(raw) : null
+}
+
+export async function openMatter(request: IncomingMessage, response: ServerResponse) {
+  const body = (await readJsonBody(request)) as {
+    clientId?: string
+    matterNumber?: string
+    title?: string
+    practiceArea?: string
+    opposingParties?: Array<{ name: string; contact?: Record<string, string> }>
+  } | null
+  if (!body?.clientId || !body.matterNumber || !body.title) {
+    response.writeHead(422, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'clientId, matterNumber, title required' }))
+    return
+  }
+  // NOTE: conflicts check not implemented — do not ship without one.
+  const result = await db.transaction(async (tx) => {
+    const [matter] = await tx
+      .insert(matters)
+      .values({
+        clientId: body.clientId!,
+        matterNumber: body.matterNumber!,
+        title: body.title!,
+        practiceArea: body.practiceArea ?? null,
+      })
+      .returning()
+    if (!matter) throw new Error('Matter not found')
+    if (body.opposingParties?.length) {
+      await tx.insert(parties).values(
+        body.opposingParties.map((p) => ({
+          matterId: matter.id,
+          role: 'opposing' as const,
+          name: p.name,
+          contact: p.contact ?? null,
+        })),
+      )
+    }
+    return matter
+  })
+  response.writeHead(201, { 'content-type': 'application/json' })
+  response.end(JSON.stringify(result))
+}
+
+export async function getMatter(_request: IncomingMessage, response: ServerResponse, matterId: string) {
+  const [matter] = await db.select().from(matters).where(eq(matters.id, matterId)).limit(1)
+  if (!matter) {
+    response.writeHead(404, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'matter not found' }))
+    return
+  }
+  const matterParties = await db.select().from(parties).where(eq(parties.matterId, matterId))
+  response.writeHead(200, { 'content-type': 'application/json' })
+  response.end(JSON.stringify({ matter, parties: matterParties }))
+}
+
+export async function logTimeEntry(request: IncomingMessage, response: ServerResponse, matterId: string) {
+  const body = (await readJsonBody(request)) as {
+    attorneyId?: string
+    workedAt?: string
+    minutes?: number
+    narrative?: string
+    billable?: boolean
+  } | null
+  if (!body?.attorneyId || !body.workedAt || !body.minutes || !body.narrative) {
+    response.writeHead(422, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'attorneyId, workedAt, minutes, narrative required' }))
+    return
+  }
+  if (!Number.isInteger(body.minutes) || body.minutes <= 0) {
+    response.writeHead(422, { 'content-type': 'application/json' })
+    response.end(JSON.stringify({ error: 'minutes must be a positive integer' }))
+    return
+  }
+  const [entry] = await db
+    .insert(timeEntries)
+    .values({
+      matterId,
+      attorneyId: body.attorneyId,
+      workedAt: new Date(body.workedAt),
+      minutes: body.minutes,
+      narrative: body.narrative,
+      billable: body.billable ?? true,
+    })
+    .returning()
+  response.writeHead(201, { 'content-type': 'application/json' })
+  response.end(JSON.stringify(entry))
+}
+
+export async function listUnbilledTime(
+  _request: IncomingMessage,
+  response: ServerResponse,
+  matterId: string,
+) {
+  const rows = await db
+    .select()
+    .from(timeEntries)
+    .where(and(eq(timeEntries.matterId, matterId), eq(timeEntries.billable, true)))
+  const unbilled = rows.filter((r) => r.invoiceId === null)
+  response.writeHead(200, { 'content-type': 'application/json' })
+  response.end(JSON.stringify({ entries: unbilled }))
+}

package/registry/layers/framework/legal-case-mgmt/files/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node --watch --experimental-strip-types src/server.ts",
+    "start": "node --experimental-strip-types src/server.ts",
+    "typecheck": "tsc --noEmit",
+    "validate": "node validate-legal.mjs",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.36.0",
+    "postgres": "^3.4.5",
+    "decimal.js": "^10.4.3"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.30.0",
+    "typescript": "^5.9.0",
+    "@types/node": "^20.17.0"
+  }
+}

package/registry/layers/framework/legal-case-mgmt/files/schema.ts

@@ -0,0 +1,148 @@
+// Legal practice-management schema. Matter-centric: every document, party,
+// time entry, and invoice belongs to a Matter. Documents are content-addressed
+// (immutable); time entries are immutable once invoiced.
+import { pgTable, uuid, varchar, timestamp, integer, jsonb, text, boolean, numeric, index, uniqueIndex, pgEnum } from 'drizzle-orm/pg-core'
+import { relations, sql } from 'drizzle-orm'
+
+export const matterStatusEnum = pgEnum('matter_status', ['open', 'closed', 'archived'])
+export const partyRoleEnum = pgEnum('party_role', ['client', 'opposing', 'witness', 'counsel', 'other'])
+export const invoiceStatusEnum = pgEnum('invoice_status', ['draft', 'sent', 'paid', 'void'])
+
+export const clients = pgTable('clients', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  displayName: varchar('display_name', { length: 200 }).notNull(),
+  email: varchar('email', { length: 254 }),
+  billingAddress: jsonb('billing_address').$type<Record<string, string>>(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+})
+
+export const attorneys = pgTable('attorneys', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  displayName: varchar('display_name', { length: 200 }).notNull(),
+  email: varchar('email', { length: 254 }).notNull().unique(),
+  barNumber: varchar('bar_number', { length: 64 }),
+  jurisdiction: varchar('jurisdiction', { length: 8 }), // e.g. "CA", "NY"
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+})
+
+export const matters = pgTable(
+  'matters',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    clientId: uuid('client_id').notNull().references(() => clients.id, { onDelete: 'restrict' }),
+    matterNumber: varchar('matter_number', { length: 64 }).notNull(),
+    title: varchar('title', { length: 500 }).notNull(),
+    practiceArea: varchar('practice_area', { length: 64 }),
+    status: matterStatusEnum('status').notNull().default('open'),
+    openedAt: timestamp('opened_at', { withTimezone: true }).notNull().defaultNow(),
+    closedAt: timestamp('closed_at', { withTimezone: true }),
+  },
+  (t) => ({
+    matterNumberUniq: uniqueIndex('matters_matter_number_uniq').on(t.matterNumber),
+    clientIdx: index('matters_client_idx').on(t.clientId),
+  }),
+)
+
+export const parties = pgTable('parties', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  matterId: uuid('matter_id').notNull().references(() => matters.id, { onDelete: 'cascade' }),
+  role: partyRoleEnum('role').notNull(),
+  name: varchar('name', { length: 300 }).notNull(),
+  contact: jsonb('contact').$type<Record<string, string>>(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+})
+
+export const documents = pgTable(
+  'documents',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    matterId: uuid('matter_id').notNull().references(() => matters.id, { onDelete: 'restrict' }),
+    // Content address: sha256 of the file bytes, hex-encoded. Collision = identity.
+    contentHash: varchar('content_hash', { length: 64 }).notNull(),
+    uri: text('uri').notNull(), // s3://... or file://... — WHERE the bytes live
+    filename: varchar('filename', { length: 500 }).notNull(),
+    mimeType: varchar('mime_type', { length: 128 }),
+    sizeBytes: integer('size_bytes'),
+    uploadedByAttorneyId: uuid('uploaded_by').references(() => attorneys.id),
+    uploadedAt: timestamp('uploaded_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    matterHashUniq: uniqueIndex('documents_matter_hash_uniq').on(t.matterId, t.contentHash),
+    matterIdx: index('documents_matter_idx').on(t.matterId),
+  }),
+)
+
+export const billingRates = pgTable(
+  'billing_rates',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    attorneyId: uuid('attorney_id').notNull().references(() => attorneys.id, { onDelete: 'restrict' }),
+    effectiveAt: timestamp('effective_at', { withTimezone: true }).notNull(),
+    // Integer cents to avoid floats entirely at the storage layer.
+    hourlyRateCents: integer('hourly_rate_cents').notNull(),
+    currency: varchar('currency', { length: 3 }).notNull().default('USD'),
+  },
+  (t) => ({
+    attorneyEffective: index('billing_rates_attorney_eff_idx').on(t.attorneyId, t.effectiveAt),
+  }),
+)
+
+export const invoices = pgTable(
+  'invoices',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    matterId: uuid('matter_id').notNull().references(() => matters.id, { onDelete: 'restrict' }),
+    clientId: uuid('client_id').notNull().references(() => clients.id, { onDelete: 'restrict' }),
+    invoiceNumber: varchar('invoice_number', { length: 64 }).notNull(),
+    status: invoiceStatusEnum('status').notNull().default('draft'),
+    // Totals as NUMERIC for accurate display; integer cents is computed from entries.
+    subtotalCents: integer('subtotal_cents').notNull().default(0),
+    totalCents: integer('total_cents').notNull().default(0),
+    currency: varchar('currency', { length: 3 }).notNull().default('USD'),
+    issuedAt: timestamp('issued_at', { withTimezone: true }),
+    paidAt: timestamp('paid_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({ invoiceNumberUniq: uniqueIndex('invoices_number_uniq').on(t.invoiceNumber) }),
+)
+
+export const timeEntries = pgTable(
+  'time_entries',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    matterId: uuid('matter_id').notNull().references(() => matters.id, { onDelete: 'restrict' }),
+    attorneyId: uuid('attorney_id').notNull().references(() => attorneys.id, { onDelete: 'restrict' }),
+    workedAt: timestamp('worked_at', { withTimezone: true }).notNull(),
+    // Integer minutes. Firms that bill in 6-minute increments round at invoice time, not here.
+    minutes: integer('minutes').notNull(),
+    narrative: text('narrative').notNull(),
+    billable: boolean('billable').notNull().default(true),
+    invoiceId: uuid('invoice_id').references(() => invoices.id, { onDelete: 'restrict' }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => ({
+    matterWorkedIdx: index('time_entries_matter_worked_idx').on(t.matterId, t.workedAt),
+    attorneyWorkedIdx: index('time_entries_attorney_worked_idx').on(t.attorneyId, t.workedAt),
+    unbilledIdx: index('time_entries_unbilled_idx').on(t.matterId).where(sql`invoice_id IS NULL`),
+  }),
+)
+
+export const mattersRelations = relations(matters, ({ many, one }) => ({
+  client: one(clients, { fields: [matters.clientId], references: [clients.id] }),
+  parties: many(parties),
+  documents: many(documents),
+  timeEntries: many(timeEntries),
+  invoices: many(invoices),
+}))
+
+export const timeEntriesRelations = relations(timeEntries, ({ one }) => ({
+  matter: one(matters, { fields: [timeEntries.matterId], references: [matters.id] }),
+  attorney: one(attorneys, { fields: [timeEntries.attorneyId], references: [attorneys.id] }),
+  invoice: one(invoices, { fields: [timeEntries.invoiceId], references: [invoices.id] }),
+}))
+
+export type Matter = typeof matters.$inferSelect
+export type TimeEntry = typeof timeEntries.$inferSelect
+export type Invoice = typeof invoices.$inferSelect
+export type BillingRate = typeof billingRates.$inferSelect
+export type Document = typeof documents.$inferSelect