oneie/one/knowledge/ontology-index.md

Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.

---
title: Ontology Index
dimension: knowledge
category: ontology-index.md
tags: 6-dimensions, architecture, ontology
related_dimensions: connections, events, people, things
scope: global
created: 2025-11-03
updated: 2025-11-03
version: 1.0.0
ai_context: |
  This document is part of the knowledge dimension in the ontology-index.md category.
  Location: one/knowledge/ontology-index.md
  Purpose: Documents ontology documentation index
  Related dimensions: connections, events, people, things
  For AI agents: Read this to understand ontology index.
---

# Ontology Documentation Index

**Complete navigation for all ONE Ontology architecture documentation**

**Version:** 1.0.0
**Last Updated:** 2025-10-20
**Status:** Production Ready

---

## Getting Started

### 📚 Complete Guide (Start Here)

**[ONE Ontology Complete Guide](../../ONE Ontology-COMPLETE-GUIDE.md)**

- **47 pages** of comprehensive documentation
- Everything from quick start to advanced patterns
- Migration guides, API reference, troubleshooting
- **Recommended for:** Everyone (new and experienced)

### ⚡ Quick Start

**[Quick Start Guide](./ontology-quickstart.md)**

- Get running in 5 minutes
- Step-by-step setup instructions
- Example implementations
- **Recommended for:** New users

### 📖 Developer Guides

**[Developer Guide](./ontology-developer-guide.md)**

- Architecture deep dive
- YAML format specification
- Type generation internals
- Best practices and advanced patterns
- **Recommended for:** Developers building features

**[Migration Guide](./ontology-migration-guide.md)**

- Step-by-step migration process
- From hardcoded schema to ONE Ontology
- Data migration strategies
- Rollback procedures
- **Recommended for:** Teams migrating existing projects

### 📝 Quick Reference

**[Cheat Sheet](./ontology-cheatsheet.md)**

- Quick commands
- YAML templates
- Common code patterns
- Type reference
- **Recommended for:** Daily development

---

## Ontology Specifications

### Core Ontologies (6 Files)

All ontology specifications are in `/one/knowledge/`:

1. **[ontology-core.yaml](./ontology-core.yaml)**
   - Base types always loaded
   - 5 thing types: page, user, file, link, note
   - 4 connection types: created_by, updated_by, viewed_by, favorited_by
   - 4 event types: thing_created, thing_updated, thing_deleted, thing_viewed

2. **[ontology-blog.yaml](./ontology-blog.yaml)**
   - Blog and content publishing
   - Extends: core
   - 2 thing types: blog_post, blog_category
   - 1 connection type: posted_in
   - 2 event types: blog_post_published, blog_post_viewed

3. **[ontology-portfolio.yaml](./ontology-portfolio.yaml)**
   - Portfolio and project showcase
   - Extends: core
   - 2 thing types: project, case_study
   - 1 connection type: belongs_to_portfolio
   - 1 event type: project_viewed

4. **[ontology-courses.yaml](./ontology-courses.yaml)**
   - E-learning and course management
   - Extends: core
   - 4 thing types: course, lesson, quiz, certificate
   - 2 connection types: enrolled_in, part_of
   - 4 event types: enrolled_in_course, lesson_completed, quiz_submitted, certificate_earned

5. **[ontology-community.yaml](./ontology-community.yaml)**
   - Social features and community
   - Extends: core
   - 3 thing types: forum_topic, forum_reply, direct_message
   - 2 connection types: follows, member_of
   - 4 event types: topic_created, topic_replied, message_sent, user_followed

6. **[ontology-tokens.yaml](./ontology-tokens.yaml)**
   - Token economy
   - Extends: core
   - 2 thing types: token, token_holder
   - 1 connection type: holds_tokens
   - 3 event types: tokens_purchased, tokens_sold, tokens_transferred

---

## Implementation Documentation

### Backend Components

**[Ontology Loader README](../../backend/lib/ONTOLOGY-LOADER-README.md)**

- Load and compose ontologies
- API reference for loader functions
- Usage patterns
- Caching and performance

**[Type Generator](../../backend/lib/type-generator.ts)**

- Source code for TypeScript type generation
- 338 lines of implementation
- Generates unions, constants, type guards

**[Ontology Validator](../../backend/lib/ontology-validator.ts)**

- Source code for composition validation
- 389 lines of implementation
- Detects duplicates, circular dependencies, conflicts

**[Generate Script](../../backend/scripts/generate-ontology-types.ts)**

- CLI tool for type generation
- 116 lines
- Run: `bun run backend/scripts/generate-ontology-types.ts`

### Generated Types

**[Generated Types README](../../backend/convex/types/README.md)**

- Documentation for auto-generated types
- Usage examples
- Type safety guide

**[Generated Types Output](../../backend/convex/types/ontology.ts)**

- Auto-generated TypeScript types
- DO NOT EDIT MANUALLY
- Regenerated on each build

### Examples

**[Ontology Usage Examples](../../backend/convex/examples/ontology-types-usage.ts)**

- 9 real-world usage examples
- Type validation patterns
- Feature detection logic
- Mutation and query examples

**[Example Output](../../backend/convex/types/EXAMPLE-OUTPUT.md)**

- Sample generated type files
- Shows structure of generated code

---

## Testing & Validation

**[Test Report](../../backend/TEST-REPORT-ONTOLOGY.md)**

- End-to-end test report
- 33 tests, all passing (100%)
- Performance benchmarks (75ms cold, 5ms cached)
- Production readiness assessment

**[Test Suite](../../backend/lib/__tests__/ontology.test.ts)**

- Complete test suite (583 lines)
- 8 test suites covering all functionality
- Feature composition, type generation, validation, performance

---

## Implementation Summaries

**[Implementation Complete](../../ONE Ontology-IMPLEMENTATION-COMPLETE.md)**

- Executive summary of completed work
- Architecture overview
- Feature ontologies breakdown
- Success metrics

**[Type Generator Summary](../../ONTOLOGY-TYPE-GENERATOR-SUMMARY.md)**

- Type generation system overview
- How it works
- Generated code structure

---

## Architecture Documentation

### Core Ontology Specification

**[6-Dimension Ontology](./ontology.md)**

- Complete specification (Version 1.0.0)
- Groups, People, Things, Connections, Events, Knowledge
- 66+ entity types
- 25+ connection types
- 67+ event types

### Related Concepts

**[Rules](./rules.md)**

- Golden rules for AI development
- Ontology governance
- Best practices

**[Architecture](./architecture.md)**

- System architecture overview
- Layer explanations
- Technology stack

---

## Quick Commands

```bash
# Generate types from core only
cd backend
bun run scripts/generate-ontology-types.ts

# Generate with specific features
PUBLIC_FEATURES="blog,shop" bun run scripts/generate-ontology-types.ts

# Generate with all features
PUBLIC_FEATURES="blog,portfolio,courses,community,tokens" bun run scripts/generate-ontology-types.ts

# Run tests
bun test lib/__tests__/ontology.test.ts

# Start dev server (auto-generates types)
bun run dev  # Configured to run generator first
```

---

## File Locations

### Ontology Definitions

- **Location:** `/one/knowledge/ontology-*.yaml`
- **Format:** YAML
- **Count:** 6 ontologies (core + 5 features)

### Generated Types

- **Location:** `/backend/convex/types/ontology.ts`
- **Format:** TypeScript
- **Auto-generated:** YES (do not edit)

### Implementation

- **Loader:** `/backend/lib/ontology-loader.ts`
- **Validator:** `/backend/lib/ontology-validator.ts`
- **Generator:** `/backend/lib/type-generator.ts`
- **CLI:** `/backend/scripts/generate-ontology-types.ts`

### Tests

- **Test Suite:** `/backend/lib/__tests__/ontology.test.ts`
- **Test Report:** `/backend/TEST-REPORT-ONTOLOGY.md`

### Documentation

- **Complete Guide:** `/ONE Ontology-COMPLETE-GUIDE.md`
- **Quick Start:** `/one/knowledge/ontology-quickstart.md`
- **Developer Guide:** `/one/knowledge/ontology-developer-guide.md`
- **Migration Guide:** `/one/knowledge/ontology-migration-guide.md`
- **Cheat Sheet:** `/one/knowledge/ontology-cheatsheet.md`
- **This Index:** `/one/knowledge/ontology-index.md`

---

## Documentation Statistics

| Document               | Pages   | Words       | Status          |
| ---------------------- | ------- | ----------- | --------------- |
| Complete Guide         | 47      | ~12,000     | ✅ Complete     |
| Quick Start            | 12      | ~3,500      | ✅ Complete     |
| Developer Guide        | 18      | ~5,000      | ✅ Complete     |
| Migration Guide        | 20      | ~6,000      | ✅ Complete     |
| Cheat Sheet            | 8       | ~2,000      | ✅ Complete     |
| Loader README          | 15      | ~4,500      | ✅ Complete     |
| Test Report            | 12      | ~3,500      | ✅ Complete     |
| Implementation Summary | 14      | ~4,000      | ✅ Complete     |
| **TOTAL**              | **146** | **~40,500** | **✅ Complete** |

---

## Learning Path

### For New Users

1. Read [Quick Start Guide](./ontology-quickstart.md) (15 minutes)
2. Follow [Creating Your First Feature](../../ONE Ontology-COMPLETE-GUIDE.md#9-creating-your-first-feature) (30 minutes)
3. Explore [Example Ontologies](./ontology-core.yaml) (15 minutes)
4. Try [Usage Examples](../../backend/convex/examples/ontology-types-usage.ts) (20 minutes)

**Total Time:** ~80 minutes to full competency

### For Developers

1. Read [Developer Guide](./ontology-developer-guide.md) (45 minutes)
2. Study [Type Generation System](../../ONE Ontology-COMPLETE-GUIDE.md#6-type-generation-system) (30 minutes)
3. Review [Advanced Patterns](../../ONE Ontology-COMPLETE-GUIDE.md#10-advanced-patterns) (30 minutes)
4. Explore [Test Suite](../../backend/lib/__tests__/ontology.test.ts) (30 minutes)

**Total Time:** ~2 hours to mastery

### For Teams Migrating

1. Read [Migration Guide](./ontology-migration-guide.md) (60 minutes)
2. Audit current schema (varies)
3. Create ontology YAMLs (2-4 hours)
4. Test in staging (1-2 days)
5. Deploy to production (varies)

**Total Time:** ~1 week for typical migration

---

## Support & Community

### Getting Help

- **Documentation:** Start with [Complete Guide](../../ONE Ontology-COMPLETE-GUIDE.md)
- **Examples:** Check [Usage Examples](../../backend/convex/examples/ontology-types-usage.ts)
- **Troubleshooting:** See [Troubleshooting Section](../../ONE Ontology-COMPLETE-GUIDE.md#13-troubleshooting)
- **FAQs:** Read [FAQ Section](../../ONE Ontology-COMPLETE-GUIDE.md#14-faqs)

### Contributing

- **Share Ontologies:** Submit your custom ontologies
- **Report Issues:** GitHub issues for bugs
- **Suggest Features:** GitHub discussions for enhancements
- **Improve Docs:** PRs welcome for documentation

---

## Version History

| Version | Date       | Changes                                        |
| ------- | ---------- | ---------------------------------------------- |
| 1.0.0   | 2025-10-20 | Initial release - Complete documentation suite |

---

## Next Steps

**Choose your path:**

- 🚀 **Get Started:** Read [Quick Start Guide](./ontology-quickstart.md)
- 📚 **Learn Everything:** Read [Complete Guide](../../ONE Ontology-COMPLETE-GUIDE.md)
- 🔧 **Build Features:** Follow [Developer Guide](./ontology-developer-guide.md)
- 🔄 **Migrate:** Use [Migration Guide](./ontology-migration-guide.md)
- 📝 **Quick Reference:** Bookmark [Cheat Sheet](./ontology-cheatsheet.md)

---

**Last Updated:** 2025-10-20
**Documentation Version:** 1.0.0
**Status:** ✅ Production Ready
**Total Documentation:** 146 pages, ~40,500 words