Saltar a contenido

Estado de fase (MASTER-00): POST_MVP — documento de catálogo de producto sujeto a validación; no es alcance aprobado de Gate 0 / PoC / MVP. Gobernanza: MASTER-00.

Interaction Spec: Project Creation & Frontmatter Parsing Flow

1. Overview & System Goal

Goal

Register a new documentation project, validate the target workspace directory path or Git remote URL, initialize .docugraph/config.yaml, trigger an initial sweep by :docugraph-core to parse Markdown files and YAML frontmatter headers, populate relational graph tables (nodes and node_edges), and enforce RevenueCat Free tier project limit constraints (maximum 3 active projects).

Primary Actors

  • Authenticated User: Software developer or architect.
  • :docugraph-app Client (FE-02 ProjectDashboard): Compose Multiplatform project dashboard view.
  • Paywall Interface (FE-05 PaywallModal): RevenueCat subscription dialog.
  • :docugraph-backend Service (BE-02 project.create): Ktor asynchronous REST backend handling project initialization routines.
  • :docugraph-core Engine: KMP frontmatter parser and graph indexing engine.
  • PostgreSQL Database: Persistent store for table: projects, table: nodes, and table: node_edges.

3. State Transition Model

stateDiagram-v2
    [*] --> DashboardIdle: Authenticated User on FE-02
    DashboardIdle --> CreatingProject: Click "New Project" & Submit Details
    CreatingProject --> PaywallTriggered: Free Tier Project Limit Exceeded (>3 Projects)
    CreatingProject --> ParsingFrontmatters: Entitlement Check Passed & Config Created
    ParsingFrontmatters --> GraphReady: Frontmatters Parsed & Relational DAG Built
    ParsingFrontmatters --> SyntaxError: Malformed YAML Header Encountered
    SyntaxError --> CreatingProject: Re-configure Workspace / Fix File
    PaywallTriggered --> DashboardIdle: Dismiss Paywall Modal (FE-05)
    GraphReady --> CanvasView: Auto-navigate to FE-03 GraphCanvas

State Matrix Definitions

State Name UI Screen State (FE-02) Backend Processing State Database Action Next Available Actions
DashboardIdle Project list rendered; "New Project" button active. Server idle; waiting for request. Read existing user projects. Click "New Project"; select existing project.
CreatingProject Project creation modal displayed; form fields active. Validating request body & workspace path. None. Submit project details; cancel modal.
PaywallTriggered FE-05 PaywallModal overlays screen. Returned HTTP 403 Forbidden (PROJECT_LIMIT_EXCEEDED). None. Upgrade to Pro via RevenueCat; dismiss modal.
ParsingFrontmatters Progress indicator displays "Scanning Markdown files...". :docugraph-core reading Markdown frontmatters. INSERT INTO projects. Wait for indexing completion.
GraphReady Creation modal closes; user navigated to FE-03. Indexing complete; project status set to ACTIVE. Batch INSERT into nodes & node_edges. View 2D Graph Canvas; inspect nodes.
SyntaxError Parsing error modal displayed with file path & line details. Frontmatter parsing aborted; returned HTTP 422 (MALFORMED_YAML_HEADER). Transaction rolled back; no nodes written. Fix YAML syntax in source Markdown file; retry workspace scan.
CanvasView Active UI transitioned to FE-03 GraphCanvas. Server idle; serving graph view request. Read indexed graph (nodes, node_edges). Pan/zoom canvas; select nodes for inspection; filter subgraphs.

4. Interaction Sequence & Data Payloads

sequenceDiagram
    autonumber
    actor User
    participant FE as FE-02 (ProjectDashboard)
    participant PW as FE-05 (PaywallModal)
    participant BE as BE-02 (Ktor Backend)
    participant Core as :docugraph-core Engine
    participant DB as DB (projects, nodes, edges)

    User->>FE: Open "New Project" modal, enter Name, Workspace Path, Git Remote
    FE->>BE: POST /api/v1/projects (operationId: createProject)
    Note over FE,BE: Header: Authorization: Bearer <jwt>

    BE->>DB: SELECT COUNT(*) FROM projects WHERE owner_id = ?
    DB-->>BE: Return active project count (N)

    alt Entitlement == 'free' AND N >= 3
        BE-->>FE: 403 Forbidden { code: "PROJECT_LIMIT_EXCEEDED", limit: 3 }
        FE->>PW: Trigger FE-05 PaywallModal (RevenueCat pro_tier upgrade)
        PW-->>User: Display subscription options ($19/mo or $190/yr)
    else Entitlement Verified / Pro Tier
        BE->>DB: INSERT INTO projects (owner_id, name, path, status) VALUES (..., 'INITIALIZING')
        BE->>Core: Trigger Workspace Indexing (.docugraph/config.yaml)
        Core->>Core: Scan directory for *.md, parse YAML frontmatter headers
        Core->>Core: Construct in-memory DAG (nodes & depends_on links)
        Core->>DB: Batch INSERT nodes (table: nodes) & directed edges (table: node_edges)
        BE->>DB: UPDATE projects SET status = 'ACTIVE', node_count = X, edge_count = Y
        BE-->>FE: 201 Created { id: "prj_01H987", name, node_count, edge_count, status: "ACTIVE" }
        FE-->>User: Auto-navigate to FE-03 GraphCanvas for project prj_01H987
    end

Data Payloads

1. Project Creation Request (POST /api/v1/projects)

{
  "name": "E-Commerce Microservices Architecture",
  "workspace_path": "/home/dev/projects/ecommerce-docs",
  "git_remote_url": "https://github.com/org/ecommerce-docs.git",
  "schema_config": {
    "required_frontmatter_keys": ["id", "title", "status", "links"]
  }
}

2. Project Creation Success Response (HTTP 201 Created)

{
  "id": "prj_01H987654321",
  "owner_id": "usr_01H123456789",
  "name": "E-Commerce Microservices Architecture",
  "workspace_path": "/home/dev/projects/ecommerce-docs",
  "git_remote_url": "https://github.com/org/ecommerce-docs.git",
  "status": "ACTIVE",
  "node_count": 42,
  "edge_count": 85,
  "created_at": "2026-08-04T10:00:00Z"
}

5. Error Handling Matrix

Error Code HTTP Status Root Cause System & UI Behavior Resolution Action
PROJECT_LIMIT_EXCEEDED 403 Forbidden User on Free tier attempting to create 4th project. Intercepted by client; displays FE-05 PaywallModal. User upgrades to Pro tier via RevenueCat or deletes an existing project.
INVALID_WORKSPACE_PATH 400 Bad Request Directory path does not exist on filesystem or lacks read permissions. Inline form error on FE-02: "Directory path is invalid or unreadable." User provides valid absolute directory path.
MALFORMED_YAML_HEADER 422 Unprocessable Markdown file contains syntax errors in YAML frontmatter block. Parsing modal presents error list detailing file path, line number, and YAML error. User opens specified Markdown file and fixes YAML syntax.
DUPLICATE_PROJECT_PATH 409 Conflict Workspace path already registered by current user. Form error on FE-02: "Project workspace path is already registered." Select existing project from dashboard list.

6. Traceability Index