Structure Markdown Format

This page describes the Markdown format accepted by the Apropo draft endpoints when you validate or initialize a draft project structure.

Use this format in the JSON field structure_markdown when calling:

• POST /api/project/ai/draft/validate
• POST /api/project/ai/draft/init

The legacy alias draft_structure_markdown is still accepted for compatibility, but new integrations should prefer structure_markdown.

Purpose

Apropo Structure Markdown defines a hierarchical project estimate structure that can be parsed into the Apropo project model.

The supported hierarchy is:

Section -> Module -> Feature -> Task

Each level is represented by a Markdown heading:

# Section

## Module

### Feature

#### Task

The format can also include:

• descriptions,
• work types,
• time estimates.

Required format

The Markdown must start with the project name followed by a separator line:

Project Name
===

After that, define one or more sections.

Each opened hierarchy element must be closed with a separate line containing exactly:

===

Syntax rules

1. Project name

The first line is the project name.

AI Estimation Platform
===

2. Sections

Sections are top-level areas of the project.

# Core Platform

* description | Main business capabilities of the application.
  ** worktypes | Backend, Frontend, QA

3. Modules

Modules belong to sections.

## Authentication

* description | User authentication, registration, and session management.

4. Features

Features belong to modules.

### Login

* description | Login flow for registered users.

5. Tasks

Tasks belong to features.

#### Implement email and password login

* description | Build backend and frontend logic for email/password authentication.

- Backend: 8 h
- Frontend: 6 h
- QA: 2 h

6. Descriptions

Descriptions must use this exact prefix:

* description | Description text

7. Work types

Work types should be declared at section level.

** worktypes | Backend, Frontend, QA, PM

8. Estimates

Estimates must use the following format:

- WorkType Name: X h

Example:

- Backend: 8 h
- Frontend: 6 h
- QA: 2 h

Estimates should be placed on the lowest hierarchy level you use, usually on tasks.

Validation expectations

In practice, the validation flow expects the generated structure to include:

• a project name at the top,
• at least one section,
• section-level work types,
• at least one estimate line.

For the safest flow, validate the generated Markdown before calling draft/init.

Complete example

AI Estimation Platform
===

# Application Core

* description | Core product functionality for AI-assisted software project estimation.
  ** worktypes | Backend, Frontend, QA, PM

## User Management

* description | User accounts, authentication, authorization, and account settings.

### Authentication

* description | Login, registration, password reset, and session handling.

#### Implement email and password login

* description | Build backend and frontend flow for email/password authentication.

- Backend: 8 h
- Frontend: 6 h
- QA: 2 h
  ===

#### Implement password reset

* description | Allow users to request and confirm password reset using email tokens.

- Backend: 6 h
- Frontend: 4 h
- QA: 2 h
  ===
  ===

### Role-based access control

* description | Access control for users with different permissions.

#### Define user roles and permissions

* description | Implement role and permission model for admin, author, and observer users.

- Backend: 10 h
- Frontend: 4 h
- QA: 2 h
  ===
  ===
  ===

## Project Estimation

* description | Functionality for building WBS structures and estimating project effort.

### WBS Builder

* description | Hierarchical editor for sections, modules, features, and tasks.

#### Create WBS hierarchy editor

* description | Implement UI and backend logic for creating and editing WBS hierarchy.

- Backend: 12 h
- Frontend: 16 h
- QA: 4 h
  ===

#### Add task-level estimates

* description | Allow users to assign work type estimates to individual WBS tasks.

- Backend: 8 h
- Frontend: 8 h
- QA: 3 h
  ===
  ===
  ===
  ===

Minimal valid example

Service Planner
===

# Core

* description | Core business capabilities of the platform.
  ** worktypes | Backend, Frontend

## Authentication

* description | Login, registration and session management.

### Login

* description | User login flow.

#### Validate credentials

* description | Validate submitted credentials against identity provider.

- Backend: 6 h
- Frontend: 2 h
  ===
  ===
  ===
  ===

Invalid examples

Invalid: JSON wrapper inside the markdown field

Do not wrap the structure syntax inside JSON or any other markup inside the structure_markdown value itself.

{
  "structure": "# Core\n## Authentication"
}

Invalid: code fences in the actual markdown value

Do not include triple backticks inside the value sent as structure_markdown.

```markdown
Project Name
===
# Core
===

### Invalid: missing closing separators

Every opened hierarchy element must eventually be closed with `===`.

```markdown
Project Name
===
# Core
## Authentication
### Login
#### Implement login
- Backend: 6 h

Recommended validation flow

1. Generate Apropo Structure Markdown.
2. Call draft/validate with structure_markdown.
3. Reject or repair invalid structure.
4. Call draft/init with the validated markdown.
5. Store the original source markdown for reproducibility.

Example request body

The endpoint expects a JSON request body. The Markdown is passed inside the structure_markdown field.

{
  "workspace": "83bd8a7f-6af6-4fa3-930d-e1fcf2a0db30",
  "requirements_summary": "The client needs an AI-assisted estimation platform for creating WBS-based software project proposals.",
  "project_type": "saas",
  "draft_name": "AI Estimation Platform",
  "structure_markdown": "AI Estimation Platform\n===\n# Application Core\n* description | Core product functionality.\n** worktypes | Backend, Frontend, QA\n## User Management\n* description | Authentication and account settings.\n### Authentication\n* description | Login, registration, and password reset.\n#### Implement email and password login\n* description | Build backend and frontend flow for email/password authentication.\n- Backend: 8 h\n- Frontend: 6 h\n- QA: 2 h\n===\n===\n===\n==="
}

Practical notes

• Prefer structure_markdown over draft_structure_markdown in new integrations.
• Validate before draft/init whenever the structure is generated by a model or another automated system.
• Treat the draft status returned by draft/init as the source of truth for the next step in your workflow.
• For a full draft creation walkthrough, see Examples.