O4O Platform Development Constitution

Apply enterprise development rules from the O4O Platform constitution (CLAUDE.md v4.0) - a production-first, Core-frozen, ESM-strict monorepo governance system for TypeScript/TypeORM platforms.

What This Skill Does

Enforces architectural rules, branching strategy, entity patterns, and production-first policies from a large-scale Korean e-commerce/LMS platform. Use when working on monorepos with strict Core/Extension boundaries, TypeORM ESM compliance requirements, or production database migration workflows.

Core Principles

**Production-First (CRITICAL)**

Default environment is ALWAYS production (as of 2026-01-29)

All migrations run against production database immediately

Local development requires explicit request

Production DB: `o4o-platform-db` (34.64.96.252) in `asia-northeast3-a`

**Local Access Restrictions**

❌ Direct psql connection from local machine (blocked by firewall)

❌ Local migration scripts accessing production DB

✅ Cloud Run internal access only

✅ Admin API endpoints with audit logs

✅ Google Cloud Console SQL Editor

Instructions

1. Branch Strategy (Mandatory)

Check current branch before ANY code changes:

```bash

git branch --show-current

```

**Required flow:**

```

feature/* → develop → main (production)

```

**Rules:**

❌ NEVER commit directly to `develop`

❌ NEVER commit directly to `main`

✅ ALL work starts in `feature/*` branch

Create feature branch if not already on one:

```bash

git checkout -b feature/your-feature-name

```

2. Service Layer Hierarchy (Absolute)

**Dependency direction (enforced):**

```

Core → Extension → Feature → Service

```

**Forbidden patterns:**

❌ Core importing from Extension

❌ Core importing from Service

❌ Extension importing from Service

**Before adding imports, verify layer:**

1. Identify source layer (Core/Extension/Service)

2. Identify target layer

3. Confirm direction follows hierarchy

4. If violation detected, refactor or use event-based communication

3. TypeORM Entity ESM Rules (Zero Tolerance)

**CRITICAL: API server fails to boot if violated**

**❌ FORBIDDEN (causes circular dependency):**

```typescript

import { RelatedEntity } from './related.entity.js';

@ManyToOne(() => RelatedEntity, (e) => e.property)

relation: RelatedEntity;

```

**✅ REQUIRED (ESM-safe pattern):**

```typescript

import type { RelatedEntity } from './related.entity.js';

@ManyToOne('RelatedEntity', 'property')

relation: RelatedEntity;

```

**Enforcement checklist for every entity file:**

1. All relation imports use `import type`

2. All `@ManyToOne/@OneToMany/@ManyToMany` use string literals for entity name

3. Relation property uses string literal for inverse side

4. No functional references `() => Entity` in decorators

**If entity changes needed:**

Search codebase for similar entities as reference

Apply string literal pattern consistently

Test API server boot before committing

4. Core Freezing Policy

**Frozen Cores (structure/table changes blocked):**

`cms-core`

`auth-core`

`platform-core`

`organization-core`

**Before modifying any Core entity:**

1. Check if Core is in frozen list

2. If frozen: ❌ STOP - request explicit approval

3. If not frozen: Proceed with ESM rules (section 3)

**Alternative to Core modification:**

Create Extension-layer entity

Use foreign key to Core entity

Keep Core unchanged

5. E-commerce Order Contract (Absolute)

**For ANY service with checkout/payment:**

**Required:**

✅ Use `checkoutService.createOrder()` for all orders

✅ Assign `OrderType` at creation (immutable after)

✅ Use `ecommerce_orders` table (shared)

**Forbidden:**

❌ Create `*_orders` tables

❌ Create `*_payments` tables

❌ Change `OrderType` after creation

❌ Bypass `checkoutService`

**Valid OrderTypes:**

`DROPSHIPPING` (dropshipping-service)

`COSMETICS` (cosmetics-service)

`TOURISM` (tourism-service)

❌ `GLYCOPHARM` (blocked - legacy migration)

**Checklist before implementing checkout:**

1. Confirm service has assigned OrderType

2. Import `checkoutService` from e-commerce core

3. Call `createOrder(orderData, OrderType.YOUR_TYPE)`

4. Never create custom order tables

6. Database Migration Rules

**Production-first workflow:**

**Preferred (automated):**

```bash

Push to main branch

git push origin main

CI/CD runs migrations automatically

```

**Emergency manual execution (Admin API):**

```bash

POST /api/admin/migrations/run

Authorization: Bearer <admin_token>

```

**Direct SQL (Google Cloud Console):**

Navigate to Cloud SQL > o4o-platform-db

Use SQL Editor for DDL statements

**❌ FORBIDDEN:**

```bash

DO NOT run from local machine

tsx src/scripts/migrate.ts # BLOCKED by firewall

```

**Migration file location:**

```

src/migrations/*.ts

```

**After creating migration:**

1. Commit to feature branch

2. Merge to develop for testing

3. Merge to main for production execution

4. Verify in Cloud Run logs

7. Service Status Classification

**When creating/modifying services, set status:**

| Status | Definition |

|--------|-----------|

| `Active` | Template exists + in production use |

| `Development` | Template exists or core app in progress |

| `Experimental` | Explicitly marked as experimental |

| `Planned` | ServiceGroup defined only |

| `Legacy` | 12+ months inactive |

| `Deprecated` | Removal scheduled |

**Update status in:**

Service metadata/config files

Documentation headers

Admin dashboard

8. Work Order Standard

**Every code change requires Work Order structure:**

```markdown

조사 (Investigation)

[ ] Reproduce issue/requirement

[ ] Identify affected components

문제확정 (Problem Definition)

[ ] Root cause identified

[ ] Scope defined

최소 수정 (Minimal Fix)

[ ] Implementation plan

[ ] Changes applied

검증 (Verification)

[ ] Tested in target environment

[ ] No regressions

종료 (Completion)

[ ] Documented

[ ] Merged to appropriate branch

```

**Before starting work:**

1. Create Work Order document

2. Complete investigation phase

3. Get approval if Core changes needed

4. Proceed with minimal changes

5. Verify before merge

9. API Client Rules

**For all HTTP calls between services:**

**✅ REQUIRED:**

```typescript

import { authClient } from '@/lib/auth-client';

const response = await authClient.api.get('/endpoint');

const data = await authClient.api.post('/endpoint', payload);

```

**❌ FORBIDDEN:**

```typescript

// Hardcoded URL

fetch('https://api.example.com/endpoint')

// Direct env var usage

fetch(process.env.API_URL + '/endpoint')

// Axios without auth wrapper

axios.get('/endpoint')

```

**Why:** `authClient` handles auth tokens, environment URLs, and error handling consistently.

10. Diagnostic Infrastructure (Alpha)

**When debugging UI/API issues:**

**Standard diagnostic endpoints:**

| Endpoint | Purpose |

|----------|---------|

| `/__debug__/auth-bootstrap` | Login/session/token issues |

| `/health/detailed` | System component status |

| `/health/database` | DB connection/version |

| `/api/v1/auth/status` | Current auth state |

**Debugging workflow:**

1. **Reproduce** issue in browser

2. **Capture** JSON from diagnostic endpoint

3. **Analyze** `success`/`error`/`code` fields

4. **Trace** error code to source file

5. **Fix** and re-verify with same endpoint

**JSON response standard:**

```typescript

// Success

{ success: true, data: T }

// Error (code required)

{ success: false, error: "Human message", code: "MACHINE_CODE" }

```

11. Reference Architecture Documents

**Before working on these domains, read:**

| Domain | Required Reading |

|--------|------------------|

| Content/LMS | `docs/platform/content-core/CONTENT-CORE-OVERVIEW.md` |

| LMS Extensions | `docs/platform/lms/LMS-CORE-EXTENSION-PRINCIPLES.md` |

| Data Ownership | `docs/platform/lms/LMS-CORE-DATA-OWNERSHIP.md` |

| Navigation | `docs/platform/navigation/OPERATOR-DASHBOARD-NAVIGATION.md` |

| Extensions | `docs/platform/extensions/EXTENSION-GENERAL-GUIDE.md` |

**Key principles from these docs:**

Content has single source of truth (Content Core)

Core is immutable from Extension

Data ownership explicitly defined

Event-based communication (Core → Extension)

Unified navigation (extensions register menus)

12. Infrastructure (GCP Cloud Run)

**Production services:**

| Service | Role |

|---------|------|

| `o4o-core-api` | API server |

| `neture-web` | Neture main site |

| `glycopharm-web` | GlycoPharm (legacy) |

| `glucoseview-web` | GlucoseView |

| `k-cosmetics-web` | K-Cosmetics store |

| `kpa-society-web` | Pharmacy SaaS |

**Deployment method:**

✅ Docker container images only

❌ No source deployment

❌ No PM2/EC2/legacy IPs

Pre-Flight Checklist

Before making ANY code change:

[ ] On `feature/*` branch (not develop/main)

[ ] Reviewed service layer hierarchy

[ ] Confirmed Core freeze status if modifying Core

[ ] Using `import type` for TypeORM relations

[ ] Using `authClient` for HTTP calls

[ ] Production environment assumed (unless local explicitly requested)

[ ] Work Order structure prepared

[ ] Checked e-commerce contract if checkout/payment involved

[ ] Migration plan if schema changes needed

Examples

Example 1: Adding a new e-commerce service

**User Request:**

"Create a new subscription box service with monthly orders"

**Agent Response:**

```

Let me verify the e-commerce contract requirements first.

1. ✅ Confirmed OrderType assignment needed

2. ✅ Must use checkoutService.createOrder()

3. ✅ Register new OrderType: SUBSCRIPTION_BOX

I'll create a feature branch and follow the Work Order standard:

조사 (Investigation)

Subscription requires recurring orders

Need inventory management

Payment integration required

문제확정 (Problem Definition)

New OrderType: SUBSCRIPTION_BOX

Integration point: checkoutService

No custom order tables

최소 수정 (Minimal Fix)

1. Register OrderType in ecommerce core

2. Create subscription service (Extension layer)

3. Use checkoutService for all orders

4. Add subscription scheduling logic

Creating feature branch: feature/subscription-box-service

```

Example 2: Fixing TypeORM circular dependency

**User Request:**

"API server won't boot - circular dependency error in user entity"

**Agent Response:**

```

This is a TypeORM ESM compliance violation. Let me check the entity file.

Found issue in user.entity.ts:

❌ CURRENT (causes boot failure):

import { Organization } from './organization.entity.js';

@ManyToOne(() => Organization, (org) => org.users)

✅ REQUIRED (ESM-safe):

import type { Organization } from './organization.entity.js';

@ManyToOne('Organization', 'users')

Applying fix now. This follows section 3 of O4O Platform constitution.

```

Example 3: Production migration request

**User Request:**

"Add new columns to users table"

**Agent Response:**

```

Production-first workflow (section 6):

⚠️ Local migration scripts are BLOCKED by firewall.

Migration plan:

1. Create migration file in src/migrations/

2. Commit to feature/add-user-columns

3. Merge to develop for testing

4. Merge to main → CI/CD auto-runs migration

5. Verify in Cloud Run logs

Alternative (emergency only):

POST /api/admin/migrations/run with admin token

Would you like me to create the migration file?

```

Important Notes

This skill enforces rules from a production platform with 500k+ lines of code

"Production-first" means all work assumes production environment unless explicitly told otherwise

ESM entity rules are zero-tolerance - violations break the API server

Core freezing prevents architectural drift in mature systems

E-commerce contract prevents order data fragmentation across services

Constraints

Requires TypeScript/TypeORM monorepo architecture

Assumes GCP Cloud Run deployment model

Korean documentation references (English summaries provided)

Production database access controlled by firewall/IAM

O4O Platform Development Constitution

O4O Platform Development Constitution

What This Skill Does

Core Principles

Instructions

1. Branch Strategy (Mandatory)

2. Service Layer Hierarchy (Absolute)

3. TypeORM Entity ESM Rules (Zero Tolerance)

4. Core Freezing Policy

5. E-commerce Order Contract (Absolute)

6. Database Migration Rules

Push to main branch

CI/CD runs migrations automatically

DO NOT run from local machine

7. Service Status Classification

8. Work Order Standard

조사 (Investigation)

문제확정 (Problem Definition)

최소 수정 (Minimal Fix)

검증 (Verification)

종료 (Completion)

9. API Client Rules

10. Diagnostic Infrastructure (Alpha)

11. Reference Architecture Documents

12. Infrastructure (GCP Cloud Run)

Pre-Flight Checklist

Examples

Example 1: Adding a new e-commerce service

조사 (Investigation)

문제확정 (Problem Definition)

최소 수정 (Minimal Fix)

Example 2: Fixing TypeORM circular dependency

Example 3: Production migration request

Important Notes

Constraints

Reviews (0)