--- title: Backend Ontology Conformance dimension: things category: plans tags: 6-dimensions, backend, connections, convex, events, groups, knowledge, ontology, people, things related_dimensions: connections, events, groups, knowledge, people scope: global created: 2025-11-03 updated: 2025-11-03 version: 1.0.0 ai_context: | This document is part of the things dimension in the plans category. Location: one/things/plans/backend-ontology-conformance.md Purpose: Documents backend ontology conformance plan Related dimensions: connections, events, groups, knowledge, people For AI agents: Read this to understand backend ontology conformance. --- # Backend Ontology Conformance Plan **Status**: Draft **Created**: 2025-10-25 **Purpose**: Audit every `/backend/*` file and organize according to 6-dimension ontology **Goal**: Beautiful, neat backend structure that maps 100% to groups, people, things, connections, events, knowledge --- ## Overview The backend has accumulated 200+ files with 50+ markdown documentation files scattered in the root. These need to be: 1. **Assessed** - Confirm what each file does 2. **Classified** - Map to 6-dimension ontology 3. **Reorganized** - Move to appropriate `/one/*` directory 4. **Consolidated** - Merge duplicates 5. **Cleaned** - Delete obsolete files ### Current State **Files to organize:** ``` /backend/ (root files scattered everywhere) ├── BACKEND-STRUCTURE.md ├── CONVEX-ANALYSIS-INDEX.md ├── CONVEX-QUICK-REFERENCE.md ├── CONVEX-STRUCTURE-ANALYSIS.md ├── CONVEX-STRUCTURE-DIAGRAM.txt ├── IMPLEMENTATION-GUIDE.md ├── ONTOLOGY-FILE-STRUCTURE.md ├── ONTOLOGY-INTEGRATION-TEST-REPORT.md ├── ONTOLOGY-INTEGRATION-TEST-SUMMARY.md ├── ONTOLOGY-TEST-EXAMPLES.md ├── ONTOLOGY_QUERIES_EXAMPLE.md ├── ONTOLOGY_VISUAL_GUIDE.md ├── PERFECT-ONTOLOGY-STRUCTURE.md ├── QUERIES_ONTOLOGY_COMPLETE.md ├── QUERY_ONTOLOGY.md ├── STRUCTURE-SUMMARY.txt ├── TEST-DASHBOARD.md ├── TEST-INDEX.md ├── TEST-REPORT-ONTOLOGY.md ├── TESTING-SUMMARY.md ├── (+ 30+ more markdown files) ├── lib/ (utilities, validation, ontology tools) ├── test/ (test suites) ├── _tests_disabled/ (disabled tests - cleanup candidate) └── convex/ (main source) ├── ontologies/ (feature ontology definitions) ├── services/ (business logic services) ├── types/ (type definitions) └── (queries, mutations, actions, auth) ``` --- ## File Classification Matrix ### 1. DOCUMENTATION FILES → `/one/things/` These belong in the `/one` platform documentation: | File | Type | Destination | Action | | ------------------------------- | ------------ | --------------------------------------------- | ------------------------------ | | `README.md` | Overview | Keep (root) | REVIEW - update to 6-dimension | | `BACKEND-STRUCTURE.md` | Architecture | `/one/things/plans/backend-structure.md` | MOVE | | `CONVEX-QUICK-REFERENCE.md` | Reference | `/one/things/convex-quick-reference.md` | MOVE | | `IMPLEMENTATION-GUIDE.md` | Guide | `/one/things/implementation/backend-guide.md` | MOVE | | `ONTOLOGY-FILE-STRUCTURE.md` | Structure | DUPLICATE (consolidate) | DELETE | | `PERFECT-ONTOLOGY-STRUCTURE.md` | Reference | DUPLICATE (consolidate) | DELETE | | `CONVEX-STRUCTURE-ANALYSIS.md` | Analysis | `/one/events/backend-structure-analysis.md` | MOVE | | `CONVEX-STRUCTURE-DIAGRAM.txt` | Diagram | `/one/events/backend-structure-diagram.txt` | MOVE | | `ONTOLOGY_VISUAL_GUIDE.md` | Guide | `/one/knowledge/ontology-visual-guide.md` | MOVE | ### 2. TEST DOCUMENTATION → `/one/events/` | File | Type | Destination | Action | | -------------------------------------- | ------------- | --------------------------------------- | ----------- | | `TEST-DASHBOARD.md` | Test tracking | `/one/events/test-dashboard.md` | MOVE | | `TEST-INDEX.md` | Test index | `/one/events/test-index.md` | MOVE | | `TEST-REPORT-ONTOLOGY.md` | Test report | `/one/events/test-report-ontology.md` | MOVE | | `TESTING-SUMMARY.md` | Summary | `/one/events/testing-summary.md` | MOVE | | `ONTOLOGY-INTEGRATION-TEST-REPORT.md` | Test report | DUPLICATE | CONSOLIDATE | | `ONTOLOGY-INTEGRATION-TEST-SUMMARY.md` | Test summary | DUPLICATE | CONSOLIDATE | | `ONTOLOGY-TEST-EXAMPLES.md` | Examples | `/one/events/ontology-test-examples.md` | MOVE | | `RUN_TESTS.md` (in test/) | Test guide | KEEP (in `/backend/test/`) | REVIEW | ### 3. QUERY/API DOCUMENTATION → `/one/connections/` | File | Type | Destination | Action | | ------------------------------ | --------------- | ------------------------------------------ | ----------- | | `ONTOLOGY_QUERIES_EXAMPLE.md` | API examples | `/one/connections/api/ontology-queries.md` | MOVE | | `QUERIES_ONTOLOGY_COMPLETE.md` | Query spec | `/one/connections/api/queries-complete.md` | MOVE | | `QUERY_ONTOLOGY.md` | Query reference | DUPLICATE | CONSOLIDATE | | `convex/queries/README.md` | Query guide | Keep in `/backend/convex/` | REVIEW | ### 4. IMPLEMENTATION SPECIFICS → Keep in `/backend/` These stay in backend (source code adjacent): | File/Folder | Type | Action | | -------------------- | --------- | ---------------------------------- | | `convex/` | Source | **KEEP** - Main backend | | `convex/schema.ts` | Core | **KEEP** - 6-dimension schema | | `convex/auth.ts` | Core | **KEEP** - Authentication | | `convex/http.ts` | Core | **KEEP** - HTTP endpoints | | `convex/services/` | Code | **KEEP** - Business logic | | `convex/ontologies/` | Config | **KEEP** - Feature definitions | | `lib/` | Utilities | **KEEP** - Validation, loaders | | `test/` | Tests | **KEEP** - Test suites | | `_tests_disabled/` | Archived | **DELETE** - Obsolete | | `examples/` | Examples | MOVE to `/one/knowledge/examples/` | | `scripts/` | Scripts | KEEP in `/backend/` | | `.env.local` | Config | KEEP (secret) | ### 5. ANALYSIS FILES → `/one/events/` (Analysis & Insights) | File | Type | Destination | Action | | -------------------------- | -------- | ------------------------------------------- | ------ | | `CONVEX-ANALYSIS-INDEX.md` | Analysis | `/one/events/convex-analysis-index.md` | MOVE | | `STRUCTURE-SUMMARY.txt` | Summary | `/one/events/backend-structure-summary.txt` | MOVE | --- ## Ontology Mapping ### Groups Dimension - **Belongs**: Multi-tenant isolation configuration - **Files affected**: `convex/schema.ts` (groups table) - **Action**: REVIEW schema - ensure hierarchical nesting pattern documented ### People Dimension - **Belongs**: Authorization, roles, access control - **Files affected**: `convex/auth.ts`, `convex/auth.config.ts`, `convex/mutations/people.ts` - **Action**: KEEP all - core to platform ### Things Dimension - **Belongs**: Entity definitions, thing types, properties - **Files affected**: `convex/schema.ts` (things table), `convex/ontologies/*.json`, `convex/types/ontology.ts` - **Action**: KEEP all - core ontology definition ### Connections Dimension - **Belongs**: Relationship types, connection logic - **Files affected**: `convex/schema.ts` (connections table), `convex/mutations/connections.ts`, `convex/queries/connections.ts` - **Action**: KEEP all - core ontology definition ### Events Dimension - **Belongs**: Event logging, audit trail, action tracking - **Files affected**: `convex/schema.ts` (events table), `convex/mutations/init.ts`, `convex/internalActions/events.ts` - **Action**: KEEP all - core ontology definition ### Knowledge Dimension - **Belongs**: Embeddings, vectors, RAG, labels - **Files affected**: `convex/schema.ts` (knowledge table), `convex/mutations/knowledge.ts`, `convex/queries/knowledge.ts` - **Action**: KEEP all - core ontology definition --- ## Execution Plan (100-Cycle Sequence) ### Phase 1: AUDIT (Cycle 1-10) **Cycle 1**: Review all 200+ root files - Categorize by type (documentation, test, config, source) - List in classification matrix above **Cycle 2**: Identify duplicates - `ONTOLOGY-FILE-STRUCTURE.md` ≈ `PERFECT-ONTOLOGY-STRUCTURE.md` - `ONTOLOGY-INTEGRATION-TEST-REPORT.md` ≈ `ONTOLOGY-INTEGRATION-TEST-SUMMARY.md` - `QUERY_ONTOLOGY.md` ≈ `QUERIES_ONTOLOGY_COMPLETE.md` ≈ `ONTOLOGY_QUERIES_EXAMPLE.md` **Cycle 3**: Validate schema compliance - Check `convex/schema.ts` maps to 6 dimensions - Verify all tables present: groups, people (if separate), things, connections, events, knowledge - Check indexes, relationships, constraints **Cycle 4**: Review test coverage - Assess test files: `/backend/test/`, `_tests_disabled/` - Determine if disabled tests should be deleted or re-enabled **Cycle 5**: Audit documentation quality - Check for outdated information (e.g., "4-table" vs actual 6-dimension) - Identify contradictions between files - List accuracy issues **Cycle 6-10**: Plan-specific audits - Services audit - Types audit - Examples audit - Ontology definitions audit - Library utilities audit ### Phase 2: CONSOLIDATION (Cycle 11-20) **Cycle 11**: Merge duplicate test reports - Consolidate `ONTOLOGY-INTEGRATION-TEST-*.md` into single `/one/events/backend-integration-tests.md` **Cycle 12**: Merge query documentation - Consolidate `QUERY_ONTOLOGY.md`, `QUERIES_ONTOLOGY_COMPLETE.md`, `ONTOLOGY_QUERIES_EXAMPLE.md` - Create single `/one/connections/api/queries-guide.md` **Cycle 13**: Consolidate structure documentation - Merge `ONTOLOGY-FILE-STRUCTURE.md`, `PERFECT-ONTOLOGY-STRUCTURE.md`, `BACKEND-STRUCTURE.md` - Create single `/one/things/plans/backend-structure.md` **Cycle 14**: Audit ontology definitions - Review all files in `convex/ontologies/*.json` - Verify they're correctly referenced - Move or keep based on usage **Cycle 15**: Review service layer - Audit each file in `convex/services/` - Ensure 100% ontology-aligned - Document patterns **Cycle 16**: Audit types - Review `convex/types/ontology.ts` - Verify auto-generation works - Document type generation process **Cycle 17**: Assess examples - Review `backend/examples/` - Move to `/one/knowledge/examples/` **Cycle 18**: Evaluate disabled tests - Decide: re-enable, delete, or archive - Update `_tests_disabled/README.md` with decisions **Cycle 19**: Review lib utilities - Document each utility - Determine if needed or obsolete **Cycle 20**: Plan deletion candidates - List all files to delete - Verify no dependencies ### Phase 3: REORGANIZATION (Cycle 21-40) **Cycle 21-25**: Move documentation to `/one/` - Create target directories in `/one/things/`, `/one/events/`, `/one/connections/` - Move files per classification matrix **Cycle 26-30**: Move examples to `/one/knowledge/` - Transfer `backend/examples/` content - Create index **Cycle 31-35**: Clean up backend root - Delete moved files from `/backend/` - Verify no broken references **Cycle 36-40**: Update all references - Update links in remaining files - Verify docs build correctly - Test all cross-references ### Phase 4: CLEANUP (Cycle 41-50) **Cycle 41**: Delete disabled tests - Remove `backend/_tests_disabled/` directory - Verify no other references **Cycle 42**: Remove duplicate files - Delete consolidated files - Create deprecation notices in `/one/events/` **Cycle 43**: Update backend README - Reflect new documentation structure - Point to `/one/` for detailed guides **Cycle 44**: Create index in `/one/things/` - List all backend-related documentation - Organize by dimension **Cycle 45**: Validate 6-dimension compliance - Run ontology validator - Confirm all tables present and properly indexed - Verify schema matches specification ### Phase 5: VERIFICATION (Cycle 51-60) **Cycle 51**: Test all imports - Verify no broken imports in backend code - Check TypeScript compilation **Cycle 52**: Validate documentation links - Test all markdown links work - Verify `/one/` references valid **Cycle 53**: Review convex/schema.ts - Ensure all 6 dimensions present - Check indexes match specification - Verify type unions correct **Cycle 54**: Test convex operations - Run sample queries - Run sample mutations - Verify auth flows **Cycle 55**: Audit file permissions - Ensure secrets properly excluded (`.env.local` in `.gitignore`) - Check all source files readable **Cycle 56-60**: Final QA - Full build test - Type checking - Documentation completeness check - Manual review of organized structure --- ## Expected Outcome ### Before ``` /backend/ ├── 50+ markdown files (scattered, duplicated) ├── README.md (outdated - says "4-table" instead of 6-dimension) ├── convex/ ├── lib/ ├── test/ ├── _tests_disabled/ └── examples/ ``` ### After ``` /backend/ ├── README.md (updated - points to /one/) ├── convex/ (clean, well-organized) ├── lib/ (focused utilities only) ├── test/ (active tests only) ├── scripts/ └── package.json /one/ ├── things/plans/ │ ├── backend-ontology-conformance.md (this file) │ ├── backend-structure.md (merged docs) │ └── implementation/ │ └── backend-guide.md ├── connections/api/ │ ├── queries-guide.md (consolidated) │ └── mutations-guide.md ├── events/ │ ├── backend-integration-tests.md │ ├── backend-structure-analysis.md │ ├── testing-summary.md │ └── backend-structure-summary.txt ├── knowledge/ │ └── examples/ │ ├── complete-newsletter-example/ │ └── ontology-types-usage.ts └── people/ └── backend-roles.md (auth/people dimension) ``` --- ## Success Criteria ✅ **Every backend file mapped** to 6-dimension ontology ✅ **Zero duplicates** - consolidated or deleted ✅ **No scattered documentation** - all in `/one/` ✅ **TypeScript compilation** - zero errors ✅ **All tests passing** - or archived ✅ **Schema validation** - 6 dimensions present + indexed ✅ **Documentation links** - all working ✅ **Backend README** - updated to reflect new structure --- ## Risk Mitigation | Risk | Mitigation | | ------------------ | --------------------------------------------- | | Broken imports | Run TypeScript check after each move | | Lost documentation | Keep originals until verified in new location | | Schema changes | Don't touch schema.ts - only organize docs | | Test failures | Archive disabled tests before deleting | | Link breaks | Use grep to find all references before moving | --- ## Commands to Execute ```bash # Phase 1: Audit grep -r "THINGS\|CONNECTIONS\|EVENTS\|GROUPS\|PEOPLE\|KNOWLEDGE" /backend --include="*.md" # Phase 3: Move documentation mkdir -p /one/things/plans/ mkdir -p /one/connections/api/ mkdir -p /one/events/ mv /backend/BACKEND-STRUCTURE.md /one/things/plans/ # Phase 4: Delete duplicates rm /backend/PERFECT-ONTOLOGY-STRUCTURE.md rm /backend/ONTOLOGY-FILE-STRUCTURE.md # Phase 5: Verify cd /backend && npx tsc --noEmit ``` --- ## Next Steps 1. Review this plan 2. Approve high-level approach 3. Execute Phase 1 (Audit) - Cycle 1-10 4. Generate detailed file manifest 5. Begin consolidation (Cycle 11-20) **Status**: Ready for execution **Owner**: Agent-clean / Agent-backend **Timeline**: 100 cycles (estimated 5-10 hours of focused work)