Atlas Plan

Phase 1: Package Scaffold

Purpose: Create all config files for the @packages/db workspace package

T-001 - Scaffold @packages/db package

Create package.json, tsconfig.json, eslint.config.mjs, drizzle.config.ts, and client.ts.

Status: pending
Priority: P0
Dependencies: none

Acceptance

@packages/db/package.json with name @packages/db, scripts (build/lint/lint:fix/test:type), deps: drizzle-orm, @libsql/client; devDeps: drizzle-kit
@packages/db/tsconfig.json extending @repo/typescript/lib
@packages/db/eslint.config.mjs using base() from @repo/lint/base
@packages/db/drizzle.config.ts pointing to atlas-ops.db, migrations in migrations/, schema in @source/schema/
@packages/db/@source/client.ts exports db (Drizzle instance) and libsql (raw client); reads DATABASE_URL env, defaults to file:atlas-ops.db
Root package.json catalogs extended with drizzle-orm, drizzle-kit, @libsql/client if not present

Files

@packages/db/package.json
@packages/db/tsconfig.json
@packages/db/eslint.config.mjs
@packages/db/drizzle.config.ts
@packages/db/@source/client.ts

Phase 2: Core + Database Schema

Purpose: Define the core org hierarchy and master data tables

T-002 - schema/core.ts

Define core_group, core_entity, core_unit tables.

Status: pending
Priority: P0
Dependencies: T-001

Acceptance

coreGroup: id (text PK), name (text notNull), fullName (text)
coreEntity: id (text PK), groupId (text FK → coreGroup.id), code (text notNull), name (text notNull), fullName (text)
coreUnit: id (text PK), entityId (text FK → coreEntity.id), code (text notNull), name (text notNull)
All exported from schema/core.ts

Files

@packages/db/@source/schema/core.ts

T-003 - schema/db.ts

Define db_sex, db_organization_level, db_relation_type, db_account_type, db_organization, db_person, db_relation, db_account tables.

Status: pending
Priority: P0
Dependencies: T-002

Acceptance

All 4 lookup tables (db_sex, db_organization_level, db_relation_type, db_account_type) with id + name + source_term
dbOrganization: id, name, levelId (FK), entityId (nullable FK)
dbPerson: all fields per model.md including nullable sex_id FK, organization_id FK, isVerified (integer default 0)
dbRelation: id, fromPersonId (FK), toPersonId (FK), relationTypeId (FK), notes
dbAccount: id, accountTypeId (FK), name, personId (nullable FK), organizationId (nullable FK)

Files

@packages/db/@source/schema/db.ts

Phase 3: Catalog + Commerce + Finance Schema

Purpose: Define product catalog, orders, and financial transaction tables

T-004 - schema/catalog.ts

Define catalog_item_type, catalog_brand, catalog_brand_unit, catalog_item, catalog_item_variant, catalog_price_list, catalog_price tables.

Status: pending
Priority: P0
Dependencies: T-002

Acceptance

catalogItemType: id, name, sourceTerm
catalogBrand: id, name, description
catalogBrandUnit: brandId (FK), unitId (FK) — composite PK, no id column
catalogItem: id, brandId (FK), unitId (FK), name, category, itemTypeId (FK), sourceTerm
catalogItemVariant: id, itemId (FK), name, level, tier, sourceTerm
catalogPriceList: id, entityId (FK), unitId (nullable FK), name, currency, validFrom (text), validTo (nullable text)
catalogPrice: id, priceListId (FK), itemId (nullable FK), variantId (nullable FK), amount (real)

Files

@packages/db/@source/schema/catalog.ts

T-005 - schema/commerce.ts and schema/finance.ts

Define commerce and finance tables.

Status: pending
Priority: P0
Dependencies: T-003, T-004

Acceptance

commerceOrderType: id, name, sourceTerm
commerceCustomerType: id, name, sourceTerm
commerceOrder: all fields per model.md — entityId, unitId, accountId, participantId (nullable), itemId (nullable), variantId (nullable), orderTypeId, customerTypeId (nullable), periodYear (integer), periodMonth (integer), channelId (nullable), receiptNumber, notes, sourceFile, sourceSheet
financePaymentMethod: id, name, sourceTerm
financePaymentStatus: id, name, sourceTerm
financeTransaction: all fields per model.md — orderId (FK), date (text), amount (real), paymentChannel, paymentMethodId (nullable FK), paymentStatusId (FK), batchRef, sourceFile, sourceSheet

Files

@packages/db/@source/schema/commerce.ts
@packages/db/@source/schema/finance.ts

Phase 4: Marketing + Target Schema

Purpose: Define marketing and target tables

T-006 - schema/marketing.ts

Define all marketing tables including join tables.

Status: pending
Priority: P0
Dependencies: T-002, T-003

Acceptance

Files

@packages/db/@source/schema/marketing.ts

T-007 - schema/target.ts

Define target tables.

Status: pending
Priority: P1
Dependencies: T-002, T-005

Acceptance

targetMetric: id, name, sourceTerm
targetItem: id, entityId (FK), unitId (nullable FK), itemId (nullable FK), channelId (nullable FK), metricId (FK), periodYear (integer), periodMonth (nullable integer), value (real)

Files

@packages/db/@source/schema/target.ts

T-008 - Package index

Export all schema tables and the db client from the package index.

Status: pending
Priority: P0
Dependencies: T-002, T-003, T-004, T-005, T-006, T-007

Acceptance

@packages/db/@source/index.ts exports all schema objects from all 7 schema files
Re-exports db and libsql from client.ts
Named exports only (no default exports)

Files

@packages/db/@source/index.ts

Phase 5: Migration + Verification

Purpose: Generate and apply migrations, verify type-check

T-009 - bun install + type-check

Install dependencies and verify type-check passes.

Status: pending
Priority: P0
Dependencies: T-001, T-002, T-003, T-004, T-005, T-006, T-007, T-008

Acceptance

bun install completes
bun run test:type --filter @packages/db passes

Files

bun.lock

T-010 - Generate and apply migrations

Run Drizzle Kit to generate SQL migrations and push to atlas-ops.db.

Status: pending
Priority: P0
Dependencies: T-009

Acceptance

bunx drizzle-kit generate produces migration SQL files in @packages/db/migrations/
bunx drizzle-kit push applies to atlas-ops.db without errors
atlas-ops.db contains all 38 tables after push

Notes

Run from @packages/db/ directory

Files

@packages/db/migrations/

T-011 - Update AGENTS.md

Add db commit scope and Drizzle Kit CLI usage to AGENTS.md.

Status: pending
Priority: P1
Dependencies: T-010

Acceptance

AGENTS.md commit scopes list includes db
AGENTS.md documents Drizzle Kit commands (bunx drizzle-kit generate, migrate, push)

Files

AGENTS.md

T-012 - Verify @services/dashboard can import @packages/db

Add @packages/db as a dependency in @services/dashboard/package.json (stub — actual dashboard routes are Plan 007) to confirm the workspace reference resolves.

Status: pending
Priority: P2
Dependencies: T-009

Acceptance

@packages/db added to @services/dashboard dependencies as workspace:*
Import from '@packages/db' resolves without type error in a test file

Notes

This is a smoke test — dashboard implementation is Plan 007

On this page