diff --git a/.github/prompts/README.md b/.github/prompts/README.md index 83aa400..997a8bc 100644 --- a/.github/prompts/README.md +++ b/.github/prompts/README.md @@ -292,8 +292,8 @@ When designing protocols, benchmark against: ### Repository Documentation - [ARCHITECTURE.md](../../ARCHITECTURE.md) - System architecture -- [DEVELOPMENT_ROADMAP.md](../../DEVELOPMENT_ROADMAP.md) - Development plan -- [PRIORITIES.md](../../PRIORITIES.md) - Priority matrix +- [DEVELOPMENT_ROADMAP.md](../../internal/planning/DEVELOPMENT_ROADMAP.md) - Development plan +- [PRIORITIES.md](../../internal/planning/PRIORITIES.md) - Priority matrix - [README.md](../../README.md) - Project overview ### Protocol Documentation diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 8517f10..a5fe7a2 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -474,6 +474,6 @@ Same Protocol → Different Renderers: --- **For more details, see:** -- [DEVELOPMENT_ROADMAP.md](./DEVELOPMENT_ROADMAP.md) - Complete development plan -- [PRIORITIES.md](./PRIORITIES.md) - What to work on next +- [DEVELOPMENT_ROADMAP.md](./internal/planning/DEVELOPMENT_ROADMAP.md) - Complete development plan +- [PRIORITIES.md](./internal/planning/PRIORITIES.md) - What to work on next - [packages/spec/README.md](./packages/spec/README.md) - Technical documentation diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b368e52..eaaf118 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,8 +52,8 @@ pnpm test ### 1. Choose What to Work On Before starting, review: -- **[PRIORITIES.md](./PRIORITIES.md)** - Current sprint priorities -- **[DEVELOPMENT_ROADMAP.md](./DEVELOPMENT_ROADMAP.md)** - Long-term roadmap +- **[PRIORITIES.md](./internal/planning/PRIORITIES.md)** - Current sprint priorities +- **[DEVELOPMENT_ROADMAP.md](./internal/planning/DEVELOPMENT_ROADMAP.md)** - Long-term roadmap - **[GitHub Issues](https://github.com/objectstack-ai/spec/issues)** - Open issues ### 2. Create a Branch @@ -406,7 +406,7 @@ Brief description of changes ### Getting Help -- Review [PLANNING_INDEX.md](./PLANNING_INDEX.md) for documentation navigation +- Review [PLANNING_INDEX.md](./internal/planning/PLANNING_INDEX.md) for documentation navigation - Check [ARCHITECTURE.md](./ARCHITECTURE.md) for system design - Read [QUICK_START_IMPLEMENTATION.md](./QUICK_START_IMPLEMENTATION.md) for implementation examples diff --git a/README.md b/README.md index 97cbffe..e338c3b 100644 --- a/README.md +++ b/README.md @@ -15,29 +15,29 @@ This repository contains the core specifications, schemas, and protocols that po * **[Installation Guide](./content/docs/guides/installation.mdx):** Setup instructions * **[Contributing Guide](./CONTRIBUTING.md):** How to contribute to the project -### Planning & Architecture -* **[Development Roadmap](./DEVELOPMENT_ROADMAP.md):** Complete development plan considering all future possibilities -* **[Priority Matrix](./PRIORITIES.md):** What to work on next, sprint planning guide -* **[Architecture Diagrams](./ARCHITECTURE.md):** Visual reference for the complete system -* **[Planning Index](./PLANNING_INDEX.md):** Complete guide to navigating planning documentation +### Architecture & Design +* **[Architecture Overview](./content/docs/specifications/architecture/):** Deep dive into the three-layer architecture +* **[Data Layer (ObjectQL)](./content/docs/specifications/architecture/data-layer.mdx):** Query language and data abstraction +* **[UI Layer (ObjectUI)](./content/docs/specifications/architecture/ui-layer.mdx):** Server-driven UI protocol +* **[System Layer (ObjectOS)](./content/docs/specifications/architecture/system-layer.mdx):** Runtime kernel and plugins -### Technical Documentation +### Standards & Best Practices +* **[Naming Conventions](./content/docs/standards/naming-conventions.mdx):** Schema naming rules (camelCase vs snake_case) +* **[API Design](./content/docs/standards/api-design.mdx):** API design principles and patterns +* **[Error Handling](./content/docs/standards/error-handling.mdx):** Consistent error handling strategies +* **[Authentication](./content/docs/standards/authentication.mdx):** Authentication standards and implementation + +### Documentation Site The official documentation is built with Fumadocs and Next.js. * **[Documentation Content](./content/docs/):** MDX documentation files (concepts, specifications, references) * **[Documentation Site](./apps/docs/):** Fumadocs-powered Next.js app -* **[Technical Guides](./docs/):** In-depth technical guides and standards * **[Live Site](http://localhost:3000/docs):** Run `pnpm docs:dev` to view locally -### Architecture Deep Dives -* **[Data Layer (ObjectQL)](./docs/architecture/data-layer.md):** Query language and data abstraction -* **[UI Layer (ObjectUI)](./docs/architecture/ui-layer.md):** Server-driven UI protocol -* **[System Layer (ObjectOS)](./docs/architecture/system-layer.md):** Runtime kernel and plugins - -### Standards & Best Practices -* **[Naming Conventions](./docs/standards/naming-conventions.md):** Schema naming rules (camelCase vs snake_case) -* **[API Design](./docs/standards/api-design.md):** API design principles and patterns -* **[Error Handling](./docs/standards/error-handling.md):** Consistent error handling strategies +### Planning & Internal Docs +* **[Development Roadmap](./internal/planning/DEVELOPMENT_ROADMAP.md):** Complete development plan +* **[Priority Matrix](./internal/planning/PRIORITIES.md):** What to work on next, sprint planning guide +* **[Planning Index](./internal/planning/PLANNING_INDEX.md):** Complete guide to navigating planning documentation ## 📦 Monorepo Structure @@ -128,17 +128,17 @@ We welcome contributions! Please read our **[Contributing Guide](./CONTRIBUTING. ### Quick Start for Contributors 1. **Read the Docs**: Review [CONTRIBUTING.md](./CONTRIBUTING.md) for complete guidelines -2. **Check Priorities**: See [PRIORITIES.md](./PRIORITIES.md) for what to work on next +2. **Check Priorities**: See [PRIORITIES.md](./internal/planning/PRIORITIES.md) for what to work on next 3. **Understand Architecture**: Read [ARCHITECTURE.md](./ARCHITECTURE.md) for system overview -4. **Follow Standards**: Review [docs/standards/](./docs/standards/) for coding standards +4. **Follow Standards**: Review [content/docs/standards/](./content/docs/standards/) for coding standards ### Key Standards -- **Naming Conventions**: See [docs/standards/naming-conventions.md](./docs/standards/naming-conventions.md) +- **Naming Conventions**: See [content/docs/standards/naming-conventions.mdx](./content/docs/standards/naming-conventions.mdx) - Configuration keys: `camelCase` (e.g., `maxLength`, `referenceFilters`) - Machine names: `snake_case` (e.g., `name: 'project_task'`, `object: 'account'`) -- **API Design**: Follow [docs/standards/api-design.md](./docs/standards/api-design.md) -- **Error Handling**: Use patterns from [docs/standards/error-handling.md](./docs/standards/error-handling.md) +- **API Design**: Follow [content/docs/standards/api-design.mdx](./content/docs/standards/api-design.mdx) +- **Error Handling**: Use patterns from [content/docs/standards/error-handling.mdx](./content/docs/standards/error-handling.mdx) ### PR Checklist diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 25eb546..9cc6063 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -83,7 +83,7 @@ Version tag `v0.2.0` has been created for this release. ## 📚 Documentation Full documentation is available at: -- Development Roadmap: [DEVELOPMENT_ROADMAP.md](DEVELOPMENT_ROADMAP.md) +- Development Roadmap: [DEVELOPMENT_ROADMAP.md](internal/planning/DEVELOPMENT_ROADMAP.md) - Architecture: [ARCHITECTURE.md](ARCHITECTURE.md) - Quick Start: [QUICK_START_IMPLEMENTATION.md](QUICK_START_IMPLEMENTATION.md) diff --git a/content/docs/concepts/meta.cn.json b/content/docs/concepts/meta.cn.json index 5b44084..0572e40 100644 --- a/content/docs/concepts/meta.cn.json +++ b/content/docs/concepts/meta.cn.json @@ -5,6 +5,7 @@ "manifesto", "core-values", "architecture", + "plugin-architecture", "security_architecture", "enterprise-patterns", "ai-codex", diff --git a/docs/AI_INTEGRATION_GUIDE.md b/content/docs/guides/advanced/ai-integration-guide.mdx similarity index 99% rename from docs/AI_INTEGRATION_GUIDE.md rename to content/docs/guides/advanced/ai-integration-guide.mdx index aa8f3a6..a8d52d2 100644 --- a/docs/AI_INTEGRATION_GUIDE.md +++ b/content/docs/guides/advanced/ai-integration-guide.mdx @@ -1,3 +1,8 @@ +--- +title: AI Integration Guide +description: Complete guide to building AI-powered ObjectStack applications +--- + # AI Integration Guide > **Complete guide to building AI-powered ObjectStack applications** diff --git a/content/docs/guides/advanced/ai-integration/meta.json b/content/docs/guides/advanced/ai-integration/meta.json new file mode 100644 index 0000000..921f7be --- /dev/null +++ b/content/docs/guides/advanced/ai-integration/meta.json @@ -0,0 +1,6 @@ +{ + "title": "AI Integration", + "pages": [ + "quick-start" + ] +} diff --git a/docs/guides/ai-integration/quick-start.md b/content/docs/guides/advanced/ai-integration/quick-start.mdx similarity index 96% rename from docs/guides/ai-integration/quick-start.md rename to content/docs/guides/advanced/ai-integration/quick-start.mdx index 86cf3fd..80a9660 100644 --- a/docs/guides/ai-integration/quick-start.md +++ b/content/docs/guides/advanced/ai-integration/quick-start.mdx @@ -1,3 +1,8 @@ +--- +title: AI Integration Quick Start +description: Quick guide to integrating AI features into ObjectStack applications +--- + # AI Integration Quick Start > Quick guide to integrating AI features into ObjectStack applications diff --git a/content/docs/guides/advanced/meta.json b/content/docs/guides/advanced/meta.json new file mode 100644 index 0000000..624f5b3 --- /dev/null +++ b/content/docs/guides/advanced/meta.json @@ -0,0 +1,9 @@ +{ + "title": "Advanced Guides", + "pages": [ + "ai-integration-guide", + "ai-integration", + "security", + "performance" + ] +} diff --git a/content/docs/guides/advanced/performance/meta.json b/content/docs/guides/advanced/performance/meta.json new file mode 100644 index 0000000..e4f6c88 --- /dev/null +++ b/content/docs/guides/advanced/performance/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Performance", + "pages": [ + "optimization" + ] +} diff --git a/docs/guides/performance/optimization.md b/content/docs/guides/advanced/performance/optimization.mdx similarity index 95% rename from docs/guides/performance/optimization.md rename to content/docs/guides/advanced/performance/optimization.mdx index ba537b2..b8bb387 100644 --- a/docs/guides/performance/optimization.md +++ b/content/docs/guides/advanced/performance/optimization.mdx @@ -1,3 +1,8 @@ +--- +title: Performance Optimization +description: Strategies for optimizing ObjectStack Protocol implementations +--- + # Performance Optimization Guide > Strategies for optimizing ObjectStack Protocol implementations diff --git a/docs/guides/security/best-practices.md b/content/docs/guides/advanced/security/best-practices.mdx similarity index 94% rename from docs/guides/security/best-practices.md rename to content/docs/guides/advanced/security/best-practices.mdx index 4b315a9..a232b0f 100644 --- a/docs/guides/security/best-practices.md +++ b/content/docs/guides/advanced/security/best-practices.mdx @@ -1,3 +1,8 @@ +--- +title: Security Best Practices +description: Comprehensive security guidelines for ObjectStack Protocol implementations +--- + # Security Best Practices Guide > Comprehensive security guidelines for ObjectStack Protocol implementations diff --git a/content/docs/guides/advanced/security/meta.json b/content/docs/guides/advanced/security/meta.json new file mode 100644 index 0000000..8e41b7a --- /dev/null +++ b/content/docs/guides/advanced/security/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Security", + "pages": [ + "best-practices" + ] +} diff --git a/content/docs/guides/meta.cn.json b/content/docs/guides/meta.cn.json index b769a4f..2c44b3f 100644 --- a/content/docs/guides/meta.cn.json +++ b/content/docs/guides/meta.cn.json @@ -8,6 +8,8 @@ "field-types", "view-configuration", "workflows-validation", - "custom-driver" + "custom-driver", + "advanced", + "migration" ] } \ No newline at end of file diff --git a/content/docs/guides/meta.json b/content/docs/guides/meta.json index 78b2596..c6e96d3 100644 --- a/content/docs/guides/meta.json +++ b/content/docs/guides/meta.json @@ -8,6 +8,8 @@ "field-types", "view-configuration", "workflows-validation", - "custom-driver" + "custom-driver", + "advanced", + "migration" ] } \ No newline at end of file diff --git a/content/docs/guides/migration/index.mdx b/content/docs/guides/migration/index.mdx new file mode 100644 index 0000000..3b0ec01 --- /dev/null +++ b/content/docs/guides/migration/index.mdx @@ -0,0 +1,26 @@ +--- +title: Migration Guides +description: Guides for migrating between versions +--- + +# Migration Guides + +This section contains guides for migrating your applications between different versions of the ObjectStack Protocol. + +## Available Guides + +### [Version 0.x to 1.x Migration](/docs/guides/migration/v0-to-v1) +Complete guide for migrating from version 0.x to 1.x, including: +- Breaking changes +- New features +- Migration steps +- Code examples + +## Migration Best Practices + +1. **Read the Full Guide**: Understand all changes before starting +2. **Backup Your Data**: Always create backups before migration +3. **Test in Development**: Test the migration in a development environment first +4. **Update Dependencies**: Ensure all dependencies are compatible +5. **Review Breaking Changes**: Pay special attention to breaking changes +6. **Run Tests**: Verify all tests pass after migration diff --git a/content/docs/guides/migration/meta.json b/content/docs/guides/migration/meta.json new file mode 100644 index 0000000..71ec673 --- /dev/null +++ b/content/docs/guides/migration/meta.json @@ -0,0 +1,7 @@ +{ + "title": "Migration Guides", + "pages": [ + "index", + "v0-to-v1" + ] +} diff --git a/docs/migration/v0-to-v1.md b/content/docs/guides/migration/v0-to-v1.mdx similarity index 95% rename from docs/migration/v0-to-v1.md rename to content/docs/guides/migration/v0-to-v1.mdx index 830bd48..ee80c7a 100644 --- a/docs/migration/v0-to-v1.md +++ b/content/docs/guides/migration/v0-to-v1.mdx @@ -1,3 +1,8 @@ +--- +title: Version 0.1.x to 1.0.0 Migration +description: Guide for migrating from version 0.1.x to 1.0.0 +--- + # Migration Guide: v0.1.x to v1.0.0 > Guide for migrating from version 0.1.x to 1.0.0 diff --git a/content/docs/meta.cn.json b/content/docs/meta.cn.json index 9e6fef4..917b274 100644 --- a/content/docs/meta.cn.json +++ b/content/docs/meta.cn.json @@ -6,6 +6,7 @@ "guides", "concepts", "specifications", + "standards", "references", "faq", "troubleshooting" diff --git a/content/docs/meta.json b/content/docs/meta.json index 36353aa..f2db74f 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -6,6 +6,7 @@ "guides", "concepts", "specifications", + "standards", "references", "faq", "troubleshooting" diff --git a/content/docs/quick-start/architects.mdx b/content/docs/quick-start/architects.mdx index 825e7fb..87ad624 100644 --- a/content/docs/quick-start/architects.mdx +++ b/content/docs/quick-start/architects.mdx @@ -498,5 +498,5 @@ app.get('/legacy', legacyController); ## Resources - **[Architecture Diagrams](https://github.com/objectstack-ai/spec/blob/main/ARCHITECTURE.md)** - Visual reference -- **[Development Roadmap](https://github.com/objectstack-ai/spec/blob/main/DEVELOPMENT_ROADMAP.md)** - Future plans +- **[Development Roadmap](https://github.com/objectstack-ai/spec/blob/main/internal/planning/DEVELOPMENT_ROADMAP.md)** - Future plans - **[Contributing Guide](https://github.com/objectstack-ai/spec/blob/main/CONTRIBUTING.md)** - How to contribute diff --git a/content/docs/quick-start/backend-developers.mdx b/content/docs/quick-start/backend-developers.mdx index 4ea7ad4..5c907d5 100644 --- a/content/docs/quick-start/backend-developers.mdx +++ b/content/docs/quick-start/backend-developers.mdx @@ -390,7 +390,7 @@ describe('Task Object', () => { Coming from another framework? We've got you covered: -- [Prisma → ObjectStack](/docs/migration/prisma) -- [TypeORM → ObjectStack](/docs/migration/typeorm) -- [Sequelize → ObjectStack](/docs/migration/sequelize) -- [Mongoose → ObjectStack](/docs/migration/mongoose) +- [Prisma → ObjectStack](/docs/guides/migration/prisma) +- [TypeORM → ObjectStack](/docs/guides/migration/typeorm) +- [Sequelize → ObjectStack](/docs/guides/migration/sequelize) +- [Mongoose → ObjectStack](/docs/guides/migration/mongoose) diff --git a/content/docs/quick-start/meta.cn.json b/content/docs/quick-start/meta.cn.json new file mode 100644 index 0000000..421e76a --- /dev/null +++ b/content/docs/quick-start/meta.cn.json @@ -0,0 +1,10 @@ +{ + "title": "快速开始", + "root": true, + "pages": [ + "build-first-app", + "backend-developers", + "frontend-developers", + "architects" + ] +} diff --git a/content/docs/quick-start/meta.json b/content/docs/quick-start/meta.json index c76c281..50b528f 100644 --- a/content/docs/quick-start/meta.json +++ b/content/docs/quick-start/meta.json @@ -1,5 +1,6 @@ { "title": "Quick Start", + "root": true, "pages": [ "build-first-app", "backend-developers", diff --git a/content/docs/references/ai/meta.json b/content/docs/references/ai/meta.json index d22dfdb..161f093 100644 --- a/content/docs/references/ai/meta.json +++ b/content/docs/references/ai/meta.json @@ -1,4 +1,3 @@ { - "title": "AI Protocol", - "root": true + "title": "AI Protocol" } \ No newline at end of file diff --git a/content/docs/references/api/meta.json b/content/docs/references/api/meta.json index ab50246..0d79f0f 100644 --- a/content/docs/references/api/meta.json +++ b/content/docs/references/api/meta.json @@ -1,6 +1,5 @@ { "title": "API Protocol", - "root": true, "pages": [ "envelopes", "requests" diff --git a/content/docs/references/data/meta.json b/content/docs/references/data/meta.json index f4047f6..7929d9d 100644 --- a/content/docs/references/data/meta.json +++ b/content/docs/references/data/meta.json @@ -1,6 +1,5 @@ { "title": "Data Protocol", - "root": true, "pages": [ "core", "logic", diff --git a/content/docs/references/meta.cn.json b/content/docs/references/meta.cn.json new file mode 100644 index 0000000..a24a01a --- /dev/null +++ b/content/docs/references/meta.cn.json @@ -0,0 +1,13 @@ +{ + "title": "API 参考", + "root": true, + "pages": [ + "data", + "ui", + "system", + "ai", + "api", + "client-sdk", + "misc" + ] +} diff --git a/content/docs/references/meta.json b/content/docs/references/meta.json index bd92db0..1b0ee36 100644 --- a/content/docs/references/meta.json +++ b/content/docs/references/meta.json @@ -1,11 +1,13 @@ { - "label": "Protocol Reference", - "order": 100, + "title": "API Reference", + "root": true, "pages": [ "data", "ui", "system", "ai", + "api", + "client-sdk", "misc" ] } \ No newline at end of file diff --git a/content/docs/references/system/meta.json b/content/docs/references/system/meta.json index 8c557d8..97cd1ba 100644 --- a/content/docs/references/system/meta.json +++ b/content/docs/references/system/meta.json @@ -1,6 +1,5 @@ { "title": "System Protocol", - "root": true, "pages": [ "identity", "integration", diff --git a/content/docs/references/ui/meta.json b/content/docs/references/ui/meta.json index 2824957..762100e 100644 --- a/content/docs/references/ui/meta.json +++ b/content/docs/references/ui/meta.json @@ -1,6 +1,5 @@ { "title": "UI Protocol", - "root": true, "pages": [ "app", "views", diff --git a/docs/architecture/data-layer.md b/content/docs/specifications/architecture/data-layer.mdx similarity index 98% rename from docs/architecture/data-layer.md rename to content/docs/specifications/architecture/data-layer.mdx index 0d0ff44..205330a 100644 --- a/docs/architecture/data-layer.md +++ b/content/docs/specifications/architecture/data-layer.mdx @@ -1,3 +1,8 @@ +--- +title: ObjectQL - Data Layer Architecture +description: Deep dive into the ObjectQL (Object Query Language) data protocol architecture +--- + # ObjectQL - Data Layer Architecture > Deep dive into the ObjectQL (Object Query Language) data protocol architecture diff --git a/content/docs/specifications/architecture/index.mdx b/content/docs/specifications/architecture/index.mdx new file mode 100644 index 0000000..57d5d43 --- /dev/null +++ b/content/docs/specifications/architecture/index.mdx @@ -0,0 +1,38 @@ +--- +title: Architecture +description: Deep dive into the ObjectStack Protocol Architecture +--- + +# Architecture + +The ObjectStack Protocol is built on three core layers that work together to provide a complete metadata-driven platform. + +## Core Layers + +### [Data Layer (ObjectQL)](/docs/specifications/architecture/data-layer) +The Data Layer defines the "Shape of Data" and business logic. It includes: +- **Schema**: Objects and Fields with 23+ field types +- **Logic**: Workflows, Triggers, Validation Rules, Formulas +- **Security**: Permissions and Sharing Rules +- **Query**: Abstract Syntax Tree (AST) for unified data access + +### [UI Layer (ObjectUI)](/docs/specifications/architecture/ui-layer) +The UI Layer defines the "Shape of Interaction" for rendering interfaces: +- **Views**: Grid, Kanban, Calendar, Gantt, List configurations +- **Pages**: FlexiPage layouts with regions and components +- **Navigation**: App menus and navigation structures +- **Analytics**: Reports and Dashboards with widgets + +### [System Layer (ObjectOS)](/docs/specifications/architecture/system-layer) +The System Layer defines the "Runtime Environment": +- **Manifest**: Application packaging +- **Identity**: Authentication, Roles, Licenses +- **Integration**: Webhooks, API contracts, ETL Mappings +- **Datasource**: Driver definitions for SQL, NoSQL, SaaS connectors + +## Design Principles + +1. **Data as Code**: All configurations are expressed as declarative metadata +2. **Intent over Implementation**: Describe what you want, not how to build it +3. **Local-First**: Works offline, syncs when connected +4. **Driver Agnostic**: Abstract away storage implementation details diff --git a/content/docs/specifications/architecture/meta.json b/content/docs/specifications/architecture/meta.json new file mode 100644 index 0000000..98843bb --- /dev/null +++ b/content/docs/specifications/architecture/meta.json @@ -0,0 +1,9 @@ +{ + "title": "Architecture", + "pages": [ + "index", + "data-layer", + "ui-layer", + "system-layer" + ] +} diff --git a/docs/architecture/system-layer.md b/content/docs/specifications/architecture/system-layer.mdx similarity index 99% rename from docs/architecture/system-layer.md rename to content/docs/specifications/architecture/system-layer.mdx index b701dfc..76df94d 100644 --- a/docs/architecture/system-layer.md +++ b/content/docs/specifications/architecture/system-layer.mdx @@ -1,3 +1,8 @@ +--- +title: ObjectOS - System Layer Architecture +description: Deep dive into the ObjectOS (Operating System) runtime architecture +--- + # ObjectOS - System Layer Architecture > Deep dive into the ObjectOS (Operating System) runtime architecture diff --git a/docs/architecture/ui-layer.md b/content/docs/specifications/architecture/ui-layer.mdx similarity index 98% rename from docs/architecture/ui-layer.md rename to content/docs/specifications/architecture/ui-layer.mdx index e72a674..5e0cf71 100644 --- a/docs/architecture/ui-layer.md +++ b/content/docs/specifications/architecture/ui-layer.mdx @@ -1,3 +1,8 @@ +--- +title: ObjectUI - UI Layer Architecture +description: Deep dive into the ObjectUI (Server-Driven UI) protocol architecture +--- + # ObjectUI - UI Layer Architecture > Deep dive into the ObjectUI (Server-Driven UI) protocol architecture diff --git a/content/docs/specifications/meta.cn.json b/content/docs/specifications/meta.cn.json index 7dad234..198387a 100644 --- a/content/docs/specifications/meta.cn.json +++ b/content/docs/specifications/meta.cn.json @@ -2,6 +2,8 @@ "title": "规范", "root": true, "pages": [ + "index", + "architecture", "data", "ui", "server" diff --git a/content/docs/specifications/meta.json b/content/docs/specifications/meta.json index 355c7cb..3e94b80 100644 --- a/content/docs/specifications/meta.json +++ b/content/docs/specifications/meta.json @@ -3,6 +3,7 @@ "root": true, "pages": [ "index", + "architecture", "data", "ui", "server" diff --git a/docs/standards/api-design.md b/content/docs/standards/api-design.mdx similarity index 97% rename from docs/standards/api-design.md rename to content/docs/standards/api-design.mdx index cdf3c1b..487e9d4 100644 --- a/docs/standards/api-design.md +++ b/content/docs/standards/api-design.mdx @@ -1,3 +1,8 @@ +--- +title: API Design Principles +description: Guidelines for designing consistent and developer-friendly APIs in ObjectStack +--- + # API Design Principles > Guidelines for designing consistent and developer-friendly APIs in ObjectStack diff --git a/docs/AUTHENTICATION_STANDARD.md b/content/docs/standards/authentication.mdx similarity index 99% rename from docs/AUTHENTICATION_STANDARD.md rename to content/docs/standards/authentication.mdx index 735d362..2ba972a 100644 --- a/docs/AUTHENTICATION_STANDARD.md +++ b/content/docs/standards/authentication.mdx @@ -1,3 +1,8 @@ +--- +title: Authentication Standard +description: The standard authentication protocol specification for the ObjectStack ecosystem +--- + # ObjectStack Authentication Standard The standard authentication protocol specification for the ObjectStack ecosystem. diff --git a/docs/standards/error-handling.md b/content/docs/standards/error-handling.mdx similarity index 96% rename from docs/standards/error-handling.md rename to content/docs/standards/error-handling.mdx index 33b070d..166d979 100644 --- a/docs/standards/error-handling.md +++ b/content/docs/standards/error-handling.mdx @@ -1,3 +1,8 @@ +--- +title: Error Handling Patterns +description: Consistent error handling strategies for ObjectStack Protocol +--- + # Error Handling Patterns > Consistent error handling strategies for ObjectStack Protocol diff --git a/content/docs/standards/index.mdx b/content/docs/standards/index.mdx new file mode 100644 index 0000000..94ef5ea --- /dev/null +++ b/content/docs/standards/index.mdx @@ -0,0 +1,42 @@ +--- +title: Standards & Best Practices +description: Protocol standards and coding conventions +--- + +# Standards & Best Practices + +This section documents the standards, conventions, and best practices for working with the ObjectStack Protocol. + +## Protocol Standards + +### [Naming Conventions](/docs/standards/naming-conventions) +Learn the naming rules for schemas, fields, and identifiers: +- Configuration keys use `camelCase` +- Machine names use `snake_case` +- Schema property naming patterns + +### [API Design](/docs/standards/api-design) +API design principles and patterns for building consistent interfaces: +- RESTful conventions +- Request/Response envelopes +- Error handling patterns + +### [Error Handling](/docs/standards/error-handling) +Consistent error handling strategies across the protocol: +- Error types and codes +- Error messages and localization +- Recovery strategies + +### [Authentication](/docs/standards/authentication) +Authentication provider implementation standards: +- OAuth, SAML, LDAP integration +- Session management +- Security best practices + +## Why Standards Matter + +Standards ensure: +- **Consistency**: Predictable behavior across implementations +- **Interoperability**: Different components work together seamlessly +- **Maintainability**: Code is easier to understand and modify +- **Quality**: Best practices prevent common pitfalls diff --git a/content/docs/standards/meta.cn.json b/content/docs/standards/meta.cn.json new file mode 100644 index 0000000..c5a01a0 --- /dev/null +++ b/content/docs/standards/meta.cn.json @@ -0,0 +1,11 @@ +{ + "title": "标准", + "root": true, + "pages": [ + "index", + "naming-conventions", + "api-design", + "error-handling", + "authentication" + ] +} diff --git a/content/docs/standards/meta.json b/content/docs/standards/meta.json new file mode 100644 index 0000000..bf955c0 --- /dev/null +++ b/content/docs/standards/meta.json @@ -0,0 +1,11 @@ +{ + "title": "Standards", + "root": true, + "pages": [ + "index", + "naming-conventions", + "api-design", + "error-handling", + "authentication" + ] +} diff --git a/docs/standards/naming-conventions.md b/content/docs/standards/naming-conventions.mdx similarity index 95% rename from docs/standards/naming-conventions.md rename to content/docs/standards/naming-conventions.mdx index 92fcdf4..a34fa3d 100644 --- a/docs/standards/naming-conventions.md +++ b/content/docs/standards/naming-conventions.mdx @@ -1,3 +1,8 @@ +--- +title: Naming Conventions +description: Standardized naming rules for ObjectStack Protocol schemas and configurations +--- + # Naming Conventions > Standardized naming rules for ObjectStack Protocol schemas and configurations diff --git a/content/docs/tutorials/meta.cn.json b/content/docs/tutorials/meta.cn.json new file mode 100644 index 0000000..42851c9 --- /dev/null +++ b/content/docs/tutorials/meta.cn.json @@ -0,0 +1,5 @@ +{ + "title": "教程", + "root": true, + "pages": [] +} diff --git a/content/docs/tutorials/meta.json b/content/docs/tutorials/meta.json index cfabbef..329460c 100644 --- a/content/docs/tutorials/meta.json +++ b/content/docs/tutorials/meta.json @@ -1,3 +1,5 @@ { - "title": "Tutorials" + "title": "Tutorials", + "root": true, + "pages": [] } diff --git a/docs/README.md b/internal/OLD_DOCS_README.md similarity index 100% rename from docs/README.md rename to internal/OLD_DOCS_README.md diff --git a/internal/README.md b/internal/README.md new file mode 100644 index 0000000..7a0a45e --- /dev/null +++ b/internal/README.md @@ -0,0 +1,65 @@ +# Internal Documentation + +This directory contains internal planning and meta-documentation for the ObjectStack Protocol project. These documents are for project contributors and maintainers. + +## Directory Structure + +``` +internal/ +├── planning/ # Project planning documents +│ ├── DEVELOPMENT_ROADMAP.md # Long-term development roadmap +│ ├── PRIORITIES.md # Sprint priorities and task matrix +│ ├── PLANNING_INDEX.md # Guide to planning documentation +│ ├── QUICK_START_IMPLEMENTATION.md # Implementation quick start +│ └── SUMMARY.md # Project summary +└── OLD_DOCS_README.md # Archive of previous docs/ directory README +``` + +## Planning Documents + +### [DEVELOPMENT_ROADMAP.md](./planning/DEVELOPMENT_ROADMAP.md) +Complete development plan considering all future possibilities. This is the authoritative source for: +- Long-term vision and goals +- Feature roadmap +- Technical milestones +- Architecture evolution + +### [PRIORITIES.md](./planning/PRIORITIES.md) +Current sprint priorities and what to work on next. Use this for: +- Sprint planning +- Task prioritization +- Urgency vs. Impact matrix +- Short-term focus areas + +### [PLANNING_INDEX.md](./planning/PLANNING_INDEX.md) +Complete guide to navigating all planning documentation. Helps you find: +- Where to look for specific information +- How planning documents relate to each other +- Quick reference for contributors + +### [QUICK_START_IMPLEMENTATION.md](./planning/QUICK_START_IMPLEMENTATION.md) +Quick start guide for implementing core protocol features. + +### [SUMMARY.md](./planning/SUMMARY.md) +High-level project summary and overview. + +## For Contributors + +If you're looking for: +- **User Documentation**: See `/content/docs/` directory +- **Architecture Details**: See `/content/docs/architecture/` +- **Coding Standards**: See `/content/docs/standards/` +- **API Reference**: See `/content/docs/references/` +- **Contributing Guide**: See `/CONTRIBUTING.md` in the root + +## For Maintainers + +These internal documents are: +- **Not Published**: Not included in the public documentation site +- **Version Controlled**: Track planning decisions over time +- **Living Documents**: Updated as the project evolves +- **Reference Material**: Historical context for decisions + +--- + +**Note**: This directory was created as part of the documentation restructuring to separate internal planning documents from public protocol documentation. diff --git a/DEVELOPMENT_ROADMAP.md b/internal/planning/DEVELOPMENT_ROADMAP.md similarity index 100% rename from DEVELOPMENT_ROADMAP.md rename to internal/planning/DEVELOPMENT_ROADMAP.md diff --git a/PLANNING_INDEX.md b/internal/planning/PLANNING_INDEX.md similarity index 100% rename from PLANNING_INDEX.md rename to internal/planning/PLANNING_INDEX.md diff --git a/PRIORITIES.md b/internal/planning/PRIORITIES.md similarity index 100% rename from PRIORITIES.md rename to internal/planning/PRIORITIES.md diff --git a/QUICK_START_IMPLEMENTATION.md b/internal/planning/QUICK_START_IMPLEMENTATION.md similarity index 100% rename from QUICK_START_IMPLEMENTATION.md rename to internal/planning/QUICK_START_IMPLEMENTATION.md diff --git a/SUMMARY.md b/internal/planning/SUMMARY.md similarity index 100% rename from SUMMARY.md rename to internal/planning/SUMMARY.md