Enterprise-grade monorepo development rules for O4O Platform - ESM compliance, service architecture, Core freezing, e-commerce contracts, production-first workflow
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.
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.
**Production-First (CRITICAL)**
**Local Access Restrictions**
Check current branch before ANY code changes:
```bash
git branch --show-current
```
**Required flow:**
```
feature/* → develop → main (production)
```
**Rules:**
```bash
git checkout -b feature/your-feature-name
```
**Dependency direction (enforced):**
```
Core → Extension → Feature → Service
```
**Forbidden patterns:**
**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
**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:**
**Frozen Cores (structure/table changes blocked):**
**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:**
**For ANY service with checkout/payment:**
**Required:**
**Forbidden:**
**Valid OrderTypes:**
**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
**Production-first workflow:**
**Preferred (automated):**
```bash
git push origin main
```
**Emergency manual execution (Admin API):**
```bash
POST /api/admin/migrations/run
Authorization: Bearer <admin_token>
```
**Direct SQL (Google Cloud Console):**
**❌ FORBIDDEN:**
```bash
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
**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:**
**Every code change requires Work Order structure:**
```markdown
```
**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
**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.
**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" }
```
**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:**
**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:**
Before making ANY code change:
**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:
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
```
**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.
```
**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?
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/o4o-platform-development-constitution/raw