Phase 00: Foundation & Prerequisites

Duration: 2-3 days (reduced from 1 week) Goal: Scaffold Legacy ERP WMS app and development environment

Update (Jan 2026): Framework M Phases 1-6 are now substantially complete. Phase 00 is primarily about app scaffolding.

---

1. Framework M Status ✅

Completed

Phase	Status	Notes
Phase 1: Core Kernel	✅ Complete	Hexagonal architecture, DI
Phase 2: DocType Engine	✅ Complete	Pydantic models, SQLAlchemy mapping
Phase 3: API & Authorization	✅ Complete	Auto-CRUD, RBAC, RLS
Phase 4: Jobs & Events	✅ Complete	Taskiq + NATS, Event Bus
Phase 5: CLI Tools	✅ Complete	m start, m migrate, m new:app
Phase 6: Built-in DocTypes	✅ Complete	User, Session, File, APIKey, Auth

Available for Legacy ERP WMS

• User DocType with password hashing (argon2)
• Session management (Redis/DB backends)
• JWT authentication
• API Key authentication
• OAuth2/OIDC support
• File upload/download (Local + S3)
• Permission system (RBAC + Citadel/Cedar ready)

---

2. Legacy ERP App Scaffolding

2.1 Create Legacy ERP App Package

m new:app legacy_erp_wms

Structure:

apps/legacy_erp_wms/
├── pyproject.toml
├── src/legacy_erp_wms/
│   ├── __init__.py
│   ├── doctypes/
│   │   ├── __init__.py
│   │   ├── item.py
│   │   └── warehouse.py
│   ├── controllers/
│   └── services/
└── tests/

2.2 App Configuration

• Define legacy_erp_wms entry point in pyproject.toml
• Register with Framework M app registry
• Configure database connection (PostgreSQL)

---

3. Development Environment

3.1 Local Setup

• PostgreSQL 15+ (Docker or native)
• Redis 7+
• Python 3.12+ environment

3.2 Docker Compose (Dev)

services:
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: legacy_erp_wms
      POSTGRES_USER: legacy_erp
      POSTGRES_PASSWORD: dev_password
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  pgdata:

3.3 Environment Variables

.env

DATABASE_URL=postgresql+asyncpg://legacy_erp:dev_password@localhost:5432/legacy_erp_wms
REDIS_URL=redis://localhost:6379
SECRET_KEY=dev-secret-key-change-in-prod
DEBUG=true

---

4. Database Setup

4.1 Initial Migration

• Generate initial migration: m migrate create "initial" --autogenerate
• Run migration: m migrate

4.2 Seed Data

• Create admin user
• Basic permission setup

---

5. Verification Checklist

• m start runs without errors
• POST /api/v1/auth/login works
• Database migrations apply cleanly
• Docker build succeeds
• Basic test suite passes

---

6. Citadel Identity Integration

Citadel IAM is an abstraction layer over upstream OIDC-compatible IdPs. It handles user onboarding (admin invite, self-service) and normalizes identity from any IdP.

6.1 Architecture

┌────────────────────────────────────────────────────────────┐
│                 Upstream IdP (configurable)                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │ Keycloak │  │ Citadel  │  │ Any OIDC │                  │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘                  │
│       └─────────────┼─────────────┘                        │
└─────────────────────┼──────────────────────────────────────┘
                      │ OIDC Token
                      ▼
┌────────────────────────────────────────────────────────────┐
│                    Citadel IAM                             │
│  • Validates token with upstream IdP                       │
│  • Enriches request with X-* headers:                      │
│      X-User-Id, X-User-Attributes, X-User-Roles, etc.           │
│  • If headers too large → adds X-Profile-Lookup header     │
│  • Publishes user events to NATS                           │
└─────────────────────┬──────────────────────────────────────┘
                      │ X-* Headers (enriched)
                      ▼
┌────────────────────────────────────────────────────────────┐
│                  WMS App (Framework M)                     │
│  • Reads X-User-Id, X-User-Roles from headers              │
│  • If X-Attributes-Truncated=true set → calls Citadel /profile API    │
│  • Maps roles → WMS permissions                            │
└────────────────────────────────────────────────────────────┘

6.2 Onboarding Methods

User Type	Method	Citadel Config
HQ Staff	Admin invite (email)	invite_only: true
Depot Staff	Admin invite (email)	invite_only: true
Outlet Operators	Self-service (phone OTP)	self_service: phone
Suppliers	Self-service (email + GSTIN)	self_service: email
Beneficiaries	External app (Smart Card)	custom_flow: smart_card

6.3 Environment Configuration

# .env - Upstream IdP (tokens come from here)
OIDC_ISSUER=https://auth.example.com/realms/legacy_erp  # Keycloak/Zitadel
OIDC_CLIENT_ID=wms-app
OIDC_CLIENT_SECRET=<from-idp-admin>

# Citadel IAM API (for onboarding/user management)
CITADEL_API_URL=https://citadel.castlecraft.in/api
CITADEL_API_KEY=<from-citadel-admin>

6.4 Role Mapping

# WMS maps IdP roles (normalized by Citadel) to permissions
ROLE_MAPPING = {
    "wms_admin": ["*:*"],  # Full access
    "ho_staff": ["Item:*", "Supplier:*", "Warehouse:read"],
    "depot_staff": ["StockEntry:*", "SupplyOrder:*", "Warehouse:read"],
    "outlet_operator": ["Order:create", "Stock:read"],
    "supplier": ["SupplierPortal:*"],
}

6.5 Tasks

• Deploy upstream IdP (Keycloak/Zitadel) or use existing
• Deploy Citadel IAM (or use citadel.castlecraft.in)
• Configure Citadel to use upstream IdP
• Set up onboarding flows (admin invite, self-service)
• Create WMS client in IdP
• Set env variables in WMS
• Test login + onboarding end-to-end

---

7. Time Estimate

Task	Duration
App scaffolding	2 hours
Dev environment	2 hours
Database setup	1 hour
Citadel IAM setup	2 hours
Verification	1 hour
Total	~1 day