Architecture notes

IvoryOS is organized around a small core package plus route, runtime, parser, service, and UI layers. Keep new code in the narrowest package that owns the behavior.

System model

IvoryOS separates platform integration from workflow execution:

Python device drivers / APIs
            |
            v
     Dynamic introspection
            |
            v
    Auto-generated UI layer
            |
            v
 Visual workflow composition
            |
            v
      Workflow runtime
            |
            v
 Execution records, logs, and optimizer feedback

The codebase should preserve that boundary. Integrators expose normal Python APIs; IvoryOS generates controls and workflow actions; the runtime executes the selected workflow and records what happened.

Main package areas

  • ivoryos/core/: system-level abstractions such as module loading and return handling.

  • ivoryos/forms/: dynamic form and WTForms logic.

  • ivoryos/models/: database models.

  • ivoryos/parsers/: data serialization, JSON parsing, and type conversion.

  • ivoryos/runtime/: workflow execution, flow control, and queue behavior.

  • ivoryos/services/: backend services such as LLM-assisted design, drafts, and client proxy logic.

  • ivoryos/routes/: Flask routes and route-local request handling.

  • ivoryos/static/ and ivoryos/templates/: browser UI assets and templates.

Change guidance

  • Put user-visible behavior changes in CHANGELOG.md.

  • Put larger module-boundary or migration notes in Refactor summary.

  • Keep operator-facing runtime behavior in Run behavior; keep code-level runtime design decisions in ADRs.

  • Keep code package directories for code and docstrings; longer prose belongs under /docs/source.