9bfa626203
Major documentation restructure to improve discoverability and reduce duplication. ## Changes **Deleted (Archived/Consolidated)**: - Removed duplicate getting started guides - Archived outdated planning documents - Consolidated corpus and configuration docs - Removed obsolete vision/spec files (superseded by vision.md) - Cleaned up scrapyard and old PDFs **New Structure**: - docs/about/ - Project overview and introduction - docs/guides/ - User guides (moved from root) - docs/specs/ - Technical specifications - docs/sdk/ - SDK documentation (Go) - docs/references/ - API references - docs/archive/ - Archived historical docs - applications/aphoria/docs/advanced/ - Advanced topics - applications/aphoria/docs/reference/ - CLI reference - applications/aphoria/docs/archive/ - Archived aphoria docs **Updated**: - README.md - New root README with clear navigation - CONTRIBUTING.md - Contribution guidelines - CLAUDE.md - Updated paths to new structure - roadmap.md - Added recent completions ## Files Changed - 57 files changed - 1,977 insertions(+) - 961 deletions(-) **Net change**: +1,016 lines (added CONTRIBUTING.md, README.md, reorganized content) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
165 lines
4.4 KiB
Markdown
165 lines
4.4 KiB
Markdown
# Technical Specifications
|
|
|
|
Formal specifications and design documents for Episteme (StemeDB) features.
|
|
|
|
---
|
|
|
|
## Core Specifications
|
|
|
|
### Governance & Organization
|
|
|
|
- **[Governance Models](./governance-models.md)** - Authority hierarchies and source classification
|
|
- Source-class tiers (Regulatory, Clinical, Expert, Anecdotal)
|
|
- Decay curves and confidence over time
|
|
- Trust pack distribution and policy federation
|
|
|
|
- **[Concept Hierarchy](./concept-hierarchy.md)** - Subject/predicate organization
|
|
- Namespace structure
|
|
- Path-based indexing
|
|
- Query optimization via hierarchy
|
|
|
|
### Query & Retrieval
|
|
|
|
- **[Visual Hash Query](./visual-hash-query.md)** - Screenshot-based retrieval
|
|
- Perceptual hashing for visual anchoring
|
|
- Drift detection via image comparison
|
|
- Time-travel for "what did I see when I first read this?"
|
|
|
|
---
|
|
|
|
## Application Specifications
|
|
|
|
### Aphoria (Code Linter)
|
|
|
|
- **[Aphoria Claims API](./aphoria-claims-api.md)** - Claims management design
|
|
- AuthoredClaim vs Observation types
|
|
- Provenance, invariant, consequence structure
|
|
- CLI commands for claim lifecycle
|
|
|
|
### Domain Modeling
|
|
|
|
- **[Ontology Layer: Medical Vertical](./ontology-layer-medical-vertical.md)** - Healthcare domain
|
|
- Drug, condition, study, patient ontology
|
|
- Pharma-specific extractors and builders
|
|
- FAERS and PubMed integration patterns
|
|
|
|
---
|
|
|
|
## Specification Format
|
|
|
|
All specifications follow this structure:
|
|
|
|
```markdown
|
|
# Specification Title
|
|
|
|
## Overview
|
|
- Problem being solved
|
|
- High-level approach
|
|
- Key constraints
|
|
|
|
## Requirements
|
|
- Functional requirements
|
|
- Non-functional requirements
|
|
- Success criteria
|
|
|
|
## Design
|
|
- Architecture diagrams
|
|
- Data structures
|
|
- API surface
|
|
|
|
## Implementation Notes
|
|
- Platform-specific details
|
|
- Performance considerations
|
|
- Testing strategy
|
|
|
|
## Open Questions
|
|
- Unresolved decisions
|
|
- Future work
|
|
```
|
|
|
|
---
|
|
|
|
## Status Legend
|
|
|
|
| Status | Meaning |
|
|
|--------|---------|
|
|
| ✅ **Implemented** | Specification fully implemented and tested |
|
|
| 🚧 **In Progress** | Partial implementation, actively being built |
|
|
| 📝 **Draft** | Specification being written, not yet implemented |
|
|
| 💡 **Proposed** | Idea stage, needs more design work |
|
|
| 🗄️ **Archived** | Superseded or deprecated |
|
|
|
|
---
|
|
|
|
## Current Status
|
|
|
|
| Specification | Status | Last Updated |
|
|
|---------------|--------|--------------|
|
|
| Governance Models | ✅ Implemented | Phase 3 |
|
|
| Concept Hierarchy | ✅ Implemented | Phase 2 |
|
|
| Visual Hash Query | ✅ Implemented | Phase 3A |
|
|
| Aphoria Claims API | ✅ Implemented | Aphoria A2 |
|
|
| Ontology: Medical | ✅ Implemented | Pilot 2 |
|
|
|
|
---
|
|
|
|
## RFCs (Request for Comments)
|
|
|
|
For proposals and design discussions, see **[RFCs](../rfcs/README.md)**.
|
|
|
|
RFCs go through a review process before becoming specifications:
|
|
1. **RFC Draft** → 2. **Review** → 3. **Accepted** → 4. **Specification** → 5. **Implementation**
|
|
|
|
---
|
|
|
|
## Design Principles
|
|
|
|
All specifications must address:
|
|
|
|
1. **Epistemic Honesty**: Does it preserve disagreement or force false consensus?
|
|
2. **Append-Only**: Can it be implemented without mutating existing data?
|
|
3. **Query-Time Resolution**: Is complexity deferred to read time?
|
|
4. **Source Attribution**: Does it maintain provenance?
|
|
5. **Performance**: What are the latency/throughput characteristics?
|
|
|
|
---
|
|
|
|
## Contributing Specifications
|
|
|
|
### Creating a New Specification
|
|
|
|
1. **Check for duplicates**: Search existing specs and RFCs
|
|
2. **Start with RFC**: Draft as RFC first for feedback
|
|
3. **Use template**: Follow the specification format above
|
|
4. **Include diagrams**: Add ASCII art or mermaid diagrams
|
|
5. **Define success criteria**: How will we know it works?
|
|
|
|
### Specification Review Process
|
|
|
|
1. **Author** writes initial draft
|
|
2. **Technical review** by domain expert
|
|
3. **Architecture review** for system-wide impact
|
|
4. **Approval** by project maintainers
|
|
5. **Implementation** tracking in roadmap
|
|
|
|
---
|
|
|
|
## Related Documents
|
|
|
|
- **[RFCs](../rfcs/README.md)** - Proposals under review
|
|
- **[Architecture](../../architecture.md)** - System overview
|
|
- **[Roadmap](../../roadmap.md)** - Implementation timeline
|
|
- **[Guides](../guides/README.md)** - How-to guides for developers
|
|
|
|
---
|
|
|
|
## See Also
|
|
|
|
- **[Data Structures](../data-structures.md)** - Core types reference
|
|
- **[Consistency Model](../consistency-model.md)** - Conflict resolution
|
|
- **[Research](../research/)** - Exploratory design work
|
|
|
|
---
|
|
|
|
**[← Back to Documentation Index](../README.md)**
|