markitect-main/docs/roadmap/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](WORKPLAN.md) - Detailed implementation workplan
- [PROJECT_STRUCTURE.md](../../PROJECT_STRUCTURE.md) - Current project structure

## Usage Example (Target State)

```python
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)

```bash
# 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