vwiebe/conductor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
conductor/CODEX.md

8.5 KiB
Raw Blame History

Codex Project State

This file is the durable handoff record for Codex sessions working on Conductor. Read it before making changes, verify any drift against the current code, and update it at the end of each material work session.

Project

Conductor is a web-based, low-code builder for creating simple user interfaces backed by REST API endpoints. Its initial use case is IBM Concert Workflows / Rapid Infrastructure Automation, but the application must remain backend-agnostic.

Repository:

  • Remote: https://gitea.skeletonworks.online/vwiebe/conductor.git
  • Primary branch: main
  • Workspace: /home/vwiebe/projects/conductor
  • Initial fork commit: cce97392f72049007cf00b0aa6c77fb8c8256191

Sources of Truth

Use these files in this order:

  1. Current source code and automated tests
  2. TASKS.md for completed and remaining work
  3. docs/response-mapping-model.md for response-binding decisions
  4. shared/schemas/conductor-project.schema.json for the accepted project-document shape
  5. docs/REQUIREMENTS.md for product scope
  6. docs/ARCHITECTURE.md for architectural direction
  7. docs/BUILD_AND_TEST_PLAN.md for historical milestone and validation guidance

Some root-level documentation duplicates files under docs/. The docs/ copies should become authoritative, but that cleanup has not yet been completed.

Core Architectural Decisions

  • The canonical source of truth is one versioned JSON project document.
  • The Visual Editor, JSON Editor, Preview runtime, persistence layer, validation, and future AI tooling must operate on the same canonical document.
  • Runtime state must remain separate from the canonical document.
  • Projects are persisted in SQLite for the MVP.
  • External REST requests must flow through the backend proxy.
  • Secrets must never be intentionally exposed to the browser or stored in exported project JSON.
  • Top-level project.bindings is the canonical data-flow mechanism.
  • action.responseMapping is deprecated and must not be used for new behavior.
  • New action-response bindings should use onSuccess; legacy onClick response bindings remain compatible.
  • Production deployment should use an external reverse proxy.
  • Conductor must remain functional without AI services.

Current Implementation State

Foundation

  • React and TypeScript frontend
  • Node.js, Express, and TypeScript backend
  • SQLite database initialization and project persistence
  • Project CRUD API
  • Health and validation endpoints
  • Dockerfiles and Docker Compose configuration
  • Application layout, navigation, and shared project context
  • Project creation, save, update, and load controls

Project model and editing

  • Canonical project JSON model at schema version 0.1.0
  • Shared JSON schema and frontend TypeScript types
  • Backend schema validation
  • Valid and intentionally invalid example project definitions
  • Visual Editor and JSON Editor operating on shared project state
  • JSON syntax and schema validation before JSON Editor changes are applied

Active GUI components

All eleven schema-supported MVP components are available in the palette and have canvas, property-editor, and Preview support:

  • Label
  • Button
  • Text Input
  • Dropdown
  • Table
  • Text Area
  • Checkbox
  • Radio Group
  • Status/Message Panel
  • Container/Card (flat presentational title and body; nesting deferred)
  • JSON Viewer

REST and Preview runtime

  • REST action model supporting GET, POST, PUT, PATCH, and DELETE
  • Anonymous server-side REST execution
  • Request URL, header, query, path, and body templates
  • Normalized proxy response envelope
  • Button-triggered action execution in Preview
  • Runtime component, action, and variable state
  • Response mappings to Label and JSON Viewer values
  • Response mappings to Dropdown options
  • Response mappings to Table rows
  • Response mappings to project variables
  • Table row selection
  • Binding and action diagnostics
  • Frontend unit tests covering templates, bindings, variables, dropdowns, and tables

Known Gaps and Risks

  • Basic, Bearer, and API-key authentication types are modeled but currently execute anonymously.
  • Secure credential storage and secret resolution are not implemented.
  • The REST proxy still needs endpoint allowlisting, SSRF protection, and stricter header and URL validation.
  • Sanitized execution history and troubleshooting views are not implemented.
  • Visual REST action, event, and binding configuration workflows are incomplete; advanced configuration still relies on JSON editing.
  • Project documents are validated in the JSON Editor, but save operations still need an unconditional validation gate.
  • Backend and end-to-end automated test coverage remains incomplete.
  • IBM Bob/watsonx will not be used; AI is provider-neutral and post-MVP.
  • All five modeled authentication modes are required for MVP.
  • MVP completion is defined by the six workflows in MVP_SCOPE.md.
  • Root-level requirement and architecture documents duplicate files under docs/ and may drift.

Validation Status

The initial repository push was completed on 2026-07-18.

  • Remote main contains commit cce97392f72049007cf00b0aa6c77fb8c8256191.
  • The working tree was clean immediately after the push.
  • All :Zone.Identifier sidecar files were removed before the initial commit.
  • Node 20/npm 10 clean installs pass after repairing the frontend lockfile.
  • Frontend validation passes: 7 suites and 433 tests, plus the production build.
  • Backend build and the schema fixture matrix pass.
  • Docker Compose builds and starts both services.
  • Health, CRUD, cleanup, and restart persistence pass.
  • See BASELINE.md for exact evidence and remaining release work.
  • Manual Slice 1 acceptance passes for component configuration, Preview interaction, JSON synchronization, save/load persistence, and existing-component regressions.

Immediate Priorities

Unless the user chooses a different priority, proceed in this order:

  1. Add visual REST action, event, and binding configuration.
  2. Add validation to every project save path.
  3. Implement authentication and secure secret handling.
  4. Harden the REST proxy and add sanitized execution logging.
  5. Add backend, end-to-end, and security regression tests.
  6. Reconcile and consolidate project documentation.

See TASKS.md for the complete actionable checklist.

Working Conventions

  • Keep the canonical schema, frontend types, backend validation, examples, editor, and runtime synchronized.
  • Any project-model change must include schema validation of valid and invalid examples.
  • Prefer small, focused changes with tests over broad rewrites.
  • Do not execute deprecated action.responseMapping rules.
  • Do not store runtime values in canonical project JSON.
  • Do not commit secrets, environment files, SQLite databases, dependency directories, or build artifacts.
  • Preserve backend-agnostic REST behavior; do not couple core runtime logic to IBM-specific services.
  • Clearly distinguish implemented behavior from schema-only or planned behavior.
  • Update TASKS.md when a task is completed, added, removed, or materially re-scoped.

Session Start Checklist

At the beginning of a new session:

  • Read CODEX.md and TASKS.md.
  • Run git status --short --branch.
  • Inspect recent commits with git log --oneline -5.
  • Verify relevant source files before relying on this handoff; this document may lag behind code.
  • Confirm the selected task and its acceptance criteria.
  • Run focused baseline tests when dependencies are available.

Session End Checklist

After material work:

  • Update completed and remaining items in TASKS.md.
  • Update the implementation state, gaps, validation status, and next priority in CODEX.md.
  • Record the exact commands run and whether they passed when validation results materially changed.
  • Ensure documentation matches any schema or runtime decisions made during the session.
  • Report modified files, tests, builds, and unresolved blockers to the user.

Latest Handoff

Date: 2026-07-18

  • Completed Slice 1 by implementing Text Area, Checkbox, Radio Group, Status Panel, and Container/Card across the palette, canvas, property editor, and Preview.
  • Added runtime value and response-binding support while keeping ephemeral values out of canonical JSON.
  • Scoped Container/Card to a flat presentational title/body contract for MVP; nesting remains post-MVP.
  • Added valid-mvp-components.json and focused renderer/binding tests.
  • Validation passes: 7 frontend suites / 433 tests, frontend production build, backend TypeScript build, and the new schema fixture.
  • User completed the full manual Slice 1 checklist successfully.
  • Next recommended action: begin SLICE2.md.