NarraNexusNarraNexus
NarraNexus · Contributing

Guidelines

Code style, naming conventions, architecture rules, and contribution standards for the NarraNexus project.

Architecture Rules

The system enforces a strict top-down dependency direction. Upper layers may call lower layers, but never the reverse.

Module independenceModules never reference or depend on each other. Cross-module data flows through ContextData.extra_data.
Private implementationsBusiness logic lives in _*_impl/ directories (underscore prefix). Not exported or imported externally.
Repository patternAll database access goes through repository/ — never inline SQL in modules or services.
Schema centralizationPydantic models in schema/. Table definitions in utils/schema_registry.py.
No backward compatibilityThe project is pre-1.0. Remove dead code, rename freely. No compatibility shims.

Naming Conventions

ClassesPascalCaseAgentRuntime, NarrativeService
Functionssnake_casehook_data_gathering, get_by_id
Variablessnake_caseagent_id, ctx_data
ConstantsUPPER_SNAKE_CASEMODULE_MAP, MAX_NARRATIVES
Private packages_ prefix_agent_runtime_steps/, _module_impl/
IDsprefix + 8 random charsevt_a1b2c3d4, nar_e5f6g7h8

Database Conventions

Table registrationAll tables defined in utils/schema_registry.py via _register(TableDef(...)). auto_migrate() runs on startup.
Dual dialectEvery Column specifies both sqlite_type and mysql_type. Never assume a single backend.
Module tablesModule-specific tables use instance_ prefix (e.g., instance_jobs, instance_social_entities).
No dangerous changesNever narrow column types or completely change types. Add columns, don't modify existing ones destructively.
TimestampsUse default="(datetime('now'))" — auto-translated to CURRENT_TIMESTAMP(6) for MySQL.

Code Quality

  • All code must be in English — no Chinese in source files, comments, or variable names
  • Every file must have a file header comment with @file_name, @author, @date, @description
  • Functions must have docstrings describing workflow, args, and returns
  • Fix root causes, not symptoms — if a bug fix requires a large refactor, do it
  • No LLM or framework lock-in — design abstractions so providers can be swapped
  • Run make lint and make typecheck before submitting PRs

PR Process

When submitting a pull request:

  1. 1.Check that all affected layers are updated (API, service, implementation, schema, repository)
  2. 2.Update .mindflow/mirror/ docs for any modified code files
  3. 3.Run make lint, make typecheck, and make test
  4. 4.Verify both run.sh and desktop app behavior if you changed runtime code
  5. 5.Include before/after screenshots for any frontend changes