markitect-main/history/260208-information-space-service/README.md

Headless Information Space Service Evolution

Vision

Evolve markitect into a headless markdown transclusion-based information space service that supports:

1. HTML Rendering Mode - Render markdown to HTML, track changes, update space
2. Directory Structure Mode - Represent information as canonical directory with markdown files
3. Multiple Frontends - Support different interaction modes via clean API layer

What is an Information Space?

An Information Space is a first-class abstraction that:

• Contains a collection of documents with transclusion relationships
• Maintains persistent context for variable resolution
• Tracks document dependencies for cache invalidation
• Can be rendered to HTML or exported to directory structure
• Supports event-driven updates and subscriptions
• Can reference other spaces (composability)

Key Capabilities

Phase	Capability	Description
1	InformationSpace Entity	Space abstraction with identity, metadata, lifecycle
2	Event System	In-process pub/sub for space events
3	Persistent Transclusion	Store context state, track references
4	HTML Rendering	Render resolved markdown to HTML with caching
5	Directory Mode	Bidirectional sync with filesystem
6	API Layer	GraphQL, REST, CLI interfaces
7	Composability	Space references and inheritance
8	Git History	Optional git-based version control

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                       API Layer                              │
│   GraphQL Schema  │  REST Endpoints  │  CLI Commands        │
├─────────────────────────────────────────────────────────────┤
│                     Service Layer                            │
│   SpaceService  │  RenderService  │  SyncService            │
├─────────────────────────────────────────────────────────────┤
│                     Domain Layer                             │
│   InformationSpace │ SpaceDocument │ SpaceEvent │ EventBus  │
│   PersistentTransclusionContext │ ReferenceGraph            │
├─────────────────────────────────────────────────────────────┤
│                    Storage Layer                             │
│   SpaceRepository │ EventStore │ Cache Backend              │
├─────────────────────────────────────────────────────────────┤
│                  Existing Markitect                          │
│   DatabaseManager │ TransclusionEngine │ VariantFactory     │
│   PluginRegistry │ QueryParadigms │ ASTService              │
└─────────────────────────────────────────────────────────────┘

Integration Strategy

The Information Space Service builds on existing markitect infrastructure:

Existing Component	Integration
TransclusionContext	Extended with PersistentTransclusionContext
VariantFactory	Used for directory export/import
PluginRegistry	Add SPACE_RENDERER, SPACE_SYNC, EVENT_HANDLER types
DatabaseManager	Add space-related tables
GraphQL Schema	Extend with Space types and mutations

Project Status

• Phase 0: Project Organization (prerequisite cleanup)
• Phase 1: Foundation (Space entity, repository)
• Phase 2: Event System
• Phase 3: Persistent Transclusion
• Phase 4: HTML Rendering Mode
• Phase 5: Directory Mode
• Phase 6: API Layer
• Phase 7: Composability
• Phase 8: Git History (optional)

Documentation

• WORKPLAN.md - Detailed implementation workplan
• PROJECT_STRUCTURE.md - Current project structure

Usage Example (Target State)

from markitect.spaces import SpaceService, InformationSpace

# Create a space
service = SpaceService()
space = await service.create_space("my-docs", description="Documentation space")

# Add documents
await service.add_document(space, "/intro.md", content="# Introduction")
await service.add_document(space, "/getting-started.md", content="# Getting Started")

# Render to HTML
html_output = await service.render(space, theme="default")

# Export to directory
await service.export_to_directory(space, "./output/")

# Watch for changes
async for event in service.subscribe(space):
    print(f"Change detected: {event.type} on {event.document_path}")

CLI Commands (Target State)

# Space management
markitect space create my-space --description "My documentation"
markitect space list
markitect space show my-space

# Document management
markitect space add-doc my-space --path "/intro.md" --file ./intro.md
markitect space list-docs my-space

# Rendering
markitect space render my-space --output ./html/ --theme default

# Directory sync
markitect space sync my-space --directory ./my-space-dir/ --bidirectional

# History (Phase 8)
markitect space history log my-space
markitect space history diff my-space --rev HEAD~1

Contributing

See the main project CONTRIBUTING.md for guidelines. For this initiative specifically:

1. Follow the phased implementation order
2. Write tests before implementing features
3. Update documentation as you go
4. Use the event system for loose coupling
5. Maintain backward compatibility