Ivx Cf Contentx Standards

ContentX Engineering Standards

STATUS: DRAFT / NOT EXECUTED (2026-07-15).
The live repo uses repo-root packages (api/, pipelines/, utils/, configs/).
There is no src/contentx/. Read docs/STRUCTURE.md before placing files.
Do not migrate code into src/contentx/ unless a human explicitly runs @migrate.

Quick Reference (LIVE — use these)

⛔ HARD STOP — ignore everything below as historical draft

Everything from Legacy aspirational table through Migration Phases is a NOT-EXECUTED draft. Agents must not create src/contentx/, move packages into it, or follow the migration checklist. Path truth is docs/STRUCTURE.md + the LIVE table above. Stop here unless a human runs @migrate.

Legacy aspirational table (DO NOT FOLLOW for placement)

Directory Architecture

content-factory/
├── .cursor/           # AI IDE config (git-tracked)
├── .env.d/            # Secrets (gitignored)
├── .tmp/              # Temp files (gitignored)
├── config/            # Runtime configs
├── deploy/            # Docker, K8s, Terraform
├── docs/              # Documentation
├── logs/              # App logs (gitignored)
├── out/               # Output artifacts (gitignored)
├── scripts/           # Operational scripts
├── src/contentx/      # Source code
│   ├── domain/        # No external deps
│   ├── application/   # Use cases
│   ├── interface/     # API, CLI, MCP
│   ├── infrastructure/# External impl
│   └── pipelines/     # Domain-specific
├── tests/             # All tests
└── pyproject.toml

Dependency Rule

domain <- application <- interface
  ^                       ^
  +---- infrastructure ---+

Naming Conventions

File Management Rules

Temporary Files .tmp/

• ALL temp/scratch/cache files MUST go here
• Default lifetime: 24 hours
• Use TempManager helper:

  from contentx.infrastructure.common.temp_manager import TempManager
  
  with TempManager.temp_file(prefix="render", suffix=".mp4") as tmp:
      video.render(to=tmp)
  

Output Artifacts out/

• ALL generated content MUST go here
• Date-bucketed: out/runs/2026/07/06/{run_id}/
• Lifecycle: staging -> runs -> archive -> glacier

Environment .env.d/

• Root .env is FORBIDDEN
• Hierarchy: process env > .env.local > .env.{env} > config/
• Pydantic settings with validation:

  class Settings(BaseSettings):
      model_config = SettingsConfigDict(
          env_prefix="CONTENTX_",
          extra="forbid",
      )
  

Code Quality

Import Order

# 1. Standard library
import os

# 2. Third-party
import redis

# 3. First-party (contentx)
from contentx.domain.models import Pipeline

Type Hints

• Mandatory on all function signatures
• Use | union syntax (Python 3.12+)

Pre-Commit Checks

• ruff check . passes
• mypy src/contentx passes → typecheck live packages if configured (no src/contentx/)
• pytest passes
• No root clutter

Git Commits

type(scope): subject

body

footer

Validation Checklist

Before any commit: STRICKEN — do not enforce. Historical draft only.

• No new files in root (except allowed)
• All Python in src/contentx/ → use repo-root packages (api/, pipelines/, …)
• All env configs in .env.d/ → use root .env
• All temp files in .tmp/
• All outputs in out/ → also .working_dir/
• All logs in logs/
• Imports use from contentx... → use live package imports
• ruff check . passes (still fine)
• mypy src/contentx passes → typecheck live packages if configured
• pytest passes (still fine)

Migration Phases

STRICKEN — NOT EXECUTED. Do not run these steps. Creating src/contentx/ is forbidden unless a human explicitly runs @migrate.