Noderr Visual Guide

Your visual roadmap to understanding the Noderr ecosystem.

This guide illustrates the file structure and workflow of a Noderr project, showing how all components work together to create a systematic development environment.

Navigate with confidence through every file, folder, and workflow in a Noderr project.

---

How Noderr Components Work Together

graph TD
    subgraph "Your Input"
        User[You: Provide Goals & Decisions]
        EnvContext[noderr/environment_context.md<br/>You Configure This]
    end

    subgraph "Core System Files"
        Project[noderr/noderr_project.md<br/>Vision & Standards]
        Architecture[noderr/noderr_architecture.md<br/>System Blueprint]
        Tracker[noderr/noderr_tracker.md<br/>Progress Dashboard]
        Loop[noderr/noderr_loop.md<br/>AI Instructions]
        Log[noderr/noderr_log.md<br/>History & Memory]
    end

    subgraph "Generated During Development"
        Specs[noderr/specs/*.md<br/>Component Blueprints]
        Planning[noderr/planning/*.md<br/>Feature Analysis]
        Code[Your Code<br/>The Actual App]
    end

    subgraph "Workflow Tools"
        Prompts[noderr/prompts/<br/>NDv1.9__Spec_Verification_Checkpoint.md<br/>NDv1.9__[LOOP_2B]__Verify_Implementation.md]
    end

    %% User interactions
    User -->|Provides PrimaryGoal| Loop
    User -->|Fills out| EnvContext
    User -->|Uses| Prompts

    %% How Loop uses other files
    Loop -->|Reads context from| Project
    Loop -->|Updates status in| Tracker
    Loop -->|Logs actions to| Log
    Loop -->|Follows map in| Architecture
    Loop -->|Uses commands from| EnvContext

    %% What gets created
    Loop -->|Creates/Updates| Specs
    Loop -->|Writes| Code
    Prompts -->|Generates| Planning

    %% Dependencies
    Architecture -->|Defines all| Specs
    Tracker -->|Tracks status of| Specs
    Specs -->|Blueprint for| Code

    style User fill:#4CAF50,color:#fff
    style EnvContext fill:#4CAF50,color:#fff
    style Code fill:#FF5252,color:#fff
    style Loop fill:#FF9800,color:#fff
    style Project fill:#2196F3,color:#fff
    style Architecture fill:#2196F3,color:#fff
    style Tracker fill:#2196F3,color:#fff
    style Log fill:#2196F3,color:#fff
    style Specs fill:#9C27B0,color:#fff
    style Planning fill:#9C27B0,color:#fff
    style Prompts fill:#607D8B,color:#fff

---

At a Glance

Noderr transforms chaotic AI development into a systematic, maintainable process through a carefully orchestrated file system. This guide is your architectural blueprint—showing you exactly what lives where and why it matters.

---

Core Architecture Overview

Path	Description
📁 noderr/	← The System's Core Documents
├── noderr_project.md	The Project's Constitution & Vision
├── noderr_architecture.md	The Visual System Blueprint
├── noderr_tracker.md	The Live Progress Dashboard
├── noderr_loop.md	The AI Agent's Operational Manual
└── noderr_log.md	The Project's Immutable History
├── environment_context.md	← The Agent's Tactical "Driver"
├── specs/	← The Blueprint Library for Components
│ └── [NodeID].md	Individual Component Contracts
├── planning/	← Strategic & Brainstorming Artifacts
│ └── feature_breakdown_...md	Feature Analysis Reports
└── prompts/	← The Orchestrator's Command Toolkit
└── ND__*.md	Workflow & Loop Templates

---

The Core Documents: noderr/

The brain of your operation—five essential files that orchestrate strategy.

noderr/noderr_project.md - The Project Constitution

• Purpose: Defines the project's DNA: its vision, goals, tech stack, and coding standards.

noderr/noderr_architecture.md - The Visual Blueprint

• Purpose: An interactive system flowchart showing all components (NodeIDs) and their connections.

noderr/noderr_tracker.md - The Live Dashboard

• Purpose: Provides real-time progress monitoring of all nodes.
• Key Columns: Status, WorkGroupID (for active work), Dependencies.

noderr/noderr_loop.md - The AI's Playbook

• Purpose: The AI agent's primary instruction manual, detailing the step-by-step development process.

noderr/noderr_log.md - The Project's Memory

• Purpose: A complete, chronological history of all significant decisions, actions, and outcomes.

---

The Core Files: noderr/

noderr/environment_context.md - The Tactical "Driver"

• Purpose: Translates the abstract goals from noderr/noderr_loop.md into concrete, platform-specific commands.
• Your Role: You, the user, must fill this file out to tell the agent how to operate in your specific environment (e.g., how to run tests, commit code, etc.). The system cannot function without it.

noderr/specs - The Blueprint Library

• Purpose: Contains detailed blueprints ([NodeID].md) for every single component in the system. Each spec is a contract that is drafted before building and finalized to an "as-built" state after verification.

noderr/planning - The Strategy Room

• Purpose: A directory to store strategic planning documents generated by prompts like noderr/prompts/ND__Feature_Idea_Breakdown.md. These artifacts help shape the roadmap before work officially begins.

---

The Noderr Lifecycle

This diagram shows the updated, verification-driven lifecycle.

(Note: This is a textual representation of the workflow. The visual diagram may not be updated.)

graph LR
    Start([Start Work Session]) --> Goal{Provide<br/>PrimaryGoal}
    Goal --> L1A[LOOP 1A<br/>Propose Change Set]
    L1A --> Review1{Review<br/>Change Set}
    Review1 -->|Approved| L1B[LOOP 1B<br/>Draft Specs]
    L1B --> Review2{Review<br/>Specs}
    Review2 -->|Approved| Gate1{Spec<br/>Verification<br/>Checkpoint?};
    Gate1 --> |Yes| VerifySpecs[Verify Specs] --> L2A;
    Gate1 --> |No| L2A;
    L1B --> L2A[LOOP 2A<br/>Implement]
    L2A --> L2B[LOOP 2B<br/>Audit]
    L2B --> Review3{Review<br/>Audit}
    Review3 --> |Approved| L3[LOOP 3<br/>Finalize & Commit]
    Review3 --> |Rejected| L2A
    L3 --> Complete([Feature Complete])
    Complete --> Start

    style Start fill:#4CAF50,color:#fff
    style Complete fill:#4CAF50,color:#fff
    style Goal fill:#FF9800,color:#fff
    style Review1 fill:#FF9800,color:#fff
    style Review2 fill:#FF9800,color:#fff
    style Review3 fill:#FF9800,color:#fff
    style Gate1 fill:#E91E63,color:#fff
    style L1A fill:#2196F3,color:#fff
    style L1B fill:#2196F3,color:#fff
    style L2A fill:#2196F3,color:#fff
    style L2B fill:#2196F3,color:#fff
    style L3 fill:#2196F3,color:#fff

Phase 1: Genesis (New Project)

1. Prepare your vision → Create blueprint, project overview, and architecture
2. Build initial prototype → AI creates the first version
3. noderr/prompts/NDv1.9__Install_And_Reconcile.md → Install Noderr and reconcile with actual build

Phase 2: Development (The Loop)

1. noderr/prompts/NDv1.9__Start_Work_Session.md → Agent syncs up and is ready for a PrimaryGoal.
2. You provide a PrimaryGoal.
3. The Verification-Driven Loop Begins:
   • noderr/prompts/[LOOP_1A] Propose Change Set
   • noderr/prompts/[LOOP_1B] Draft Specs
   • (Optional) noderr/prompts/Spec_Verification_Checkpoint
   • noderr/prompts/[LOOP_2A] Implement Change Set
   • (Mandatory) noderr/prompts/[LOOP_2B] Verify Implementation
   • noderr/prompts/[LOOP_3] Finalize & Commit
4. Repeat for the next PrimaryGoal.

---

Quick Navigation Guide

I want to...	Look at...
Understand the project's vision	noderr/noderr_project.md
See the big picture	noderr/noderr_architecture.md
Check project progress	noderr/noderr_tracker.md
Find a component's details	noderr/specs/[NodeID].md
Review project history	noderr/noderr_log.md
Know how the agent works	noderr/noderr_loop.md
See how to run commands	noderr/environment_context.md
Plan future features	noderr/planning/ directory

---

File Creation and Ownership

Human-Created Files:

• noderr/environment_context.md - Must be filled out for each development environment

Noderr-Generated Initial Files:

• All files in noderr/ directory
• Empty noderr/specs/ and noderr/planning/ directories

Files Generated During Development:

• noderr/specs/[NodeID].md - Created as components are designed
• noderr/planning/feature_breakdown_*.md - Created during planning sessions
• Application source code - Created by AI following the Noderr process

---

The Noderr system separates strategy (noderr/ files) from tactics (environment_context.md), creating a powerful, portable, and professional framework for AI-driven development.