Create an Organization, Project, and Application Specification
Turn a customer idea into a tenant-scoped, versioned contract without creating a runtime prematurely.
System map · Day 04
Whole-system design
Five stable layers. Today's work is expanded and linked; the rest stays in context.
Product and authority
Covered — Generated application planeAhead — Identity and policy
People and product entry points
Source-backed today
Turns an authenticated owner request into a tenant-scoped organization, project, and application specification.
HelixWorks control plane
Source-backed today
Validates the application blueprint and owns its lifecycle before generation or runtime work begins.
Delivery and desired state
Ahead — Git desired state · CI and immutable artifacts · Argo CD reconciliation
Cloud and orchestration
Covered — Terraform and AWS APIs · Kubernetes or EKS control planeAhead — Accounts, VPC, DNS, and private paths
Compute and traffic
Covered — Worker compute · Platform service workloadsAhead — Generated app workloads · Ambient mesh data plane
Storage and evidence
Covered — Evidence and observabilityAhead — Infrastructure state · Cluster desired and live state
Product data and artifacts
Source-backed today
Commits the specification and its audit evidence in one product operation with tenant-qualified keys.
The enterprise problem and today’s slice
Enterprise problem: Free-form prompts omit ownership, data, identity, and lifecycle constraints, so generation can produce software that nobody can safely approve or retire.
Whole-course context: The service ports assign provider metadata to the control plane; today creates the first durable tenant-scoped project through those interfaces.
Today’s slice: Create the implemented organization-scoped project and embedded archetype blueprint, then specify the separate immutable application-revision record still needed for production.
End-of-day evidence: Authenticated project creation, tenant-scoped retrieval, project.created evidence, and a wrong-tenant denial are reproducible from the HTTP smoke and domain tests; revision hashes remain future evidence.
Still unsolved: No code is generated, previewed, connected, published, or deployed in this slice.
Customer outcome and implementation focus
The customer outcome is a reviewable create an organization, project, and application specification change, not a collection of requirements. This day starts with the implementation boundary, then uses the command or manifest below to produce positive, denied, and recovery evidence.
Components in focus
Studio API and specification validator; control-plane compute workload; PostgreSQL/SQLite owns organization, project, and app-spec records; cache: not involved so validation always sees the authoritative revision.
This map names the implementation boundary for this day. The service or controller changes only the state it owns; runtime and audit evidence let the operator distinguish a declared change from an effective one.
Persist and validate an application specification
Exercise the specification API
A 201 response is insufficient unless durable tenant-scoped state and audit evidence agree. The current implementation creates a project directly from an authenticated HTTP command; it has no separate organization service, PostgreSQL deployment, or versioned application-spec resource yet. Read the exact model operation in services/control_plane/domain.py.
def create(self, project_id: str, organization_id: str, name: str, actor: str, archetype: str) -> Project:
project = Project(project_id, organization_id, name, actor, blueprint={"name": name, "archetype": archetype})
project.collaborators.add(actor)
self.repository.create(project)
self._audit(project, actor, "project.created")
return project
Decision rules
Keep specifications declarative and versioned; do not mix generated source, runtime secrets, or app-user permissions into them. A new archetype is inside the platform only when the same revision contract can describe it without adding app-specific fields to core services.