feat(spaces): implement Phase 0-1 of Information Space Service
Phase 0 - Project Organization: - Create docs/PROJECT_STRUCTURE.md documenting codebase layout - Create markitect/core/ with parser, serializer, document_manager, workspace - Create markitect/schema/ consolidating 6 schema_*.py modules - Create markitect/storage/ with database module - Maintain backward compatibility via re-exports from original locations - Add docs/roadmap/information-space-service/ with README and WORKPLAN Phase 1 - Foundation (Weeks 1-3): - Week 1: Core domain models (InformationSpace, SpaceDocument, SpaceConfig, SpaceMetadata, SpaceVariable, TransclusionReference, SpaceStatus) - Week 2: Repository layer with interfaces (ISpaceRepository, IDocumentAssociationRepository, IVariableRepository, IReferenceRepository) and SQLite implementations with foreign key cascade deletes - Week 3: SpaceService orchestration layer with full CRUD, document, variable, and reference tracking operations Test coverage: 124 tests (25 model + 63 repository + 36 integration) Capabilities delivered: - CAP-001: InformationSpace entity with lifecycle management - CAP-002: SpaceRepository CRUD with SQLite backing - CAP-003: Document-Space associations with path-based organization - CAP-004: Space metadata and configuration schemas - CAP-005: Database schema with migrations Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
142
docs/roadmap/information-space-service/README.md
Normal file
142
docs/roadmap/information-space-service/README.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user