Skip to content

Commit 133e98f

Browse files
Copilothotlong
Copilot
and
hotlong
committed
feat: add comprehensive documentation structure and standards
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent e0df197 commit 133e98f

9 files changed

Lines changed: 2435 additions & 19 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 430 additions & 0 deletions
Large diffs are not rendered by default.

‎README.md‎

Lines changed: 41 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,34 @@ This repository contains the core specifications, schemas, and protocols that po
1010

1111
## 📚 Documentation
1212

13+
### Quick Start
14+
* **[Getting Started](./content/docs/guides/getting-started.mdx):** Quick introduction to ObjectStack Protocol
15+
* **[Installation Guide](./content/docs/guides/installation.mdx):** Setup instructions
16+
* **[Contributing Guide](./CONTRIBUTING.md):** How to contribute to the project
17+
1318
### Planning & Architecture
14-
* **[Development Roadmap](./DEVELOPMENT_ROADMAP.md):** Complete development plan considering all future possibilities.
15-
* **[Priority Matrix](./PRIORITIES.md):** What to work on next, sprint planning guide.
16-
* **[Architecture Diagrams](./ARCHITECTURE.md):** Visual reference for the complete system.
19+
* **[Development Roadmap](./DEVELOPMENT_ROADMAP.md):** Complete development plan considering all future possibilities
20+
* **[Priority Matrix](./PRIORITIES.md):** What to work on next, sprint planning guide
21+
* **[Architecture Diagrams](./ARCHITECTURE.md):** Visual reference for the complete system
22+
* **[Planning Index](./PLANNING_INDEX.md):** Complete guide to navigating planning documentation
1723

1824
### Technical Documentation
1925
The official documentation is built with Fumadocs and Next.js.
2026

21-
* **[Documentation Content](./content/docs/):** MDX documentation files (concepts, specifications, references).
22-
* **[Documentation Site](./apps/docs/):** Fumadocs-powered Next.js app.
23-
* **[Live Site](http://localhost:3000/docs):** Run `pnpm docs:dev` to view locally.
27+
* **[Documentation Content](./content/docs/):** MDX documentation files (concepts, specifications, references)
28+
* **[Documentation Site](./apps/docs/):** Fumadocs-powered Next.js app
29+
* **[Technical Guides](./docs/):** In-depth technical guides and standards
30+
* **[Live Site](http://localhost:3000/docs):** Run `pnpm docs:dev` to view locally
31+
32+
### Architecture Deep Dives
33+
* **[Data Layer (ObjectQL)](./docs/architecture/data-layer.md):** Query language and data abstraction
34+
* **[UI Layer (ObjectUI)](./docs/architecture/ui-layer.md):** Server-driven UI protocol
35+
* **[System Layer (ObjectOS)](./docs/architecture/system-layer.md):** Runtime kernel and plugins
36+
37+
### Standards & Best Practices
38+
* **[Naming Conventions](./docs/standards/naming-conventions.md):** Schema naming rules (camelCase vs snake_case)
39+
* **[API Design](./docs/standards/api-design.md):** API design principles and patterns
40+
* **[Error Handling](./docs/standards/error-handling.md):** Consistent error handling strategies
2441

2542
## 📦 Monorepo Structure
2643

@@ -104,31 +121,36 @@ pnpm docs:dev
104121
# Visit http://localhost:3000/docs
105122
```
106123

107-
## 🤝 Contribution
124+
## 🤝 Contributing
108125

109-
### Getting Started
110-
1. **Read the Roadmap**: Review [DEVELOPMENT_ROADMAP.md](./DEVELOPMENT_ROADMAP.md) to understand the vision.
111-
2. **Check Priorities**: See [PRIORITIES.md](./PRIORITIES.md) for what to work on next.
112-
3. **Understand Architecture**: Read [ARCHITECTURE.md](./ARCHITECTURE.md) for system overview.
126+
We welcome contributions! Please read our **[Contributing Guide](./CONTRIBUTING.md)** for detailed guidelines.
113127

114-
### Development Process
115-
1. **Code First**: Always start by defining the Zod Schema in `packages/spec/src`.
116-
2. **Write Tests**: Add comprehensive tests in `*.test.ts` files (target 80%+ coverage).
117-
3. **Generate**: Run `pnpm build` to update JSON Schemas and Documentation.
118-
4. **Commit**: Submit PR with updated Code + Schemas + Docs.
128+
### Quick Start for Contributors
119129

120-
### Naming Conventions
121-
- **Configuration Keys** (TypeScript properties): `camelCase` (e.g., `maxLength`, `referenceFilters`)
122-
- **Machine Names** (Data values): `snake_case` (e.g., `name: 'project_task'`, `object: 'account'`)
130+
1. **Read the Docs**: Review [CONTRIBUTING.md](./CONTRIBUTING.md) for complete guidelines
131+
2. **Check Priorities**: See [PRIORITIES.md](./PRIORITIES.md) for what to work on next
132+
3. **Understand Architecture**: Read [ARCHITECTURE.md](./ARCHITECTURE.md) for system overview
133+
4. **Follow Standards**: Review [docs/standards/](./docs/standards/) for coding standards
134+
135+
### Key Standards
136+
137+
- **Naming Conventions**: See [docs/standards/naming-conventions.md](./docs/standards/naming-conventions.md)
138+
- Configuration keys: `camelCase` (e.g., `maxLength`, `referenceFilters`)
139+
- Machine names: `snake_case` (e.g., `name: 'project_task'`, `object: 'account'`)
140+
- **API Design**: Follow [docs/standards/api-design.md](./docs/standards/api-design.md)
141+
- **Error Handling**: Use patterns from [docs/standards/error-handling.md](./docs/standards/error-handling.md)
123142

124143
### PR Checklist
144+
125145
- [ ] Zod schema follows naming conventions
126146
- [ ] Comprehensive JSDoc comments with `@description`
127147
- [ ] Unit tests with 80%+ coverage
128148
- [ ] Documentation with examples
129149
- [ ] JSON schema generated successfully
130150
- [ ] All existing tests pass
131151

152+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for complete details.
153+
132154
## 📄 License
133155

134156
Apach2 2.0 © ObjectStack

‎docs/README.md‎

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
# ObjectStack Protocol Documentation
2+
3+
> Comprehensive technical documentation for the ObjectStack Protocol ecosystem
4+
5+
## 📚 Documentation Structure
6+
7+
This directory contains **technical guides** and **standards** for the ObjectStack Protocol. For the main documentation site, see [`content/docs/`](../content/docs/).
8+
9+
## 📂 Directory Organization
10+
11+
```
12+
docs/
13+
├── README.md # This file - Documentation index
14+
├── guides/ # Technical how-to guides
15+
│ ├── ai-integration/ # AI feature integration guides
16+
│ ├── security/ # Security implementation guides
17+
│ └── performance/ # Performance optimization guides
18+
├── standards/ # Protocol standards and conventions
19+
│ ├── naming-conventions.md # Naming rules for schemas
20+
│ ├── api-design.md # API design principles
21+
│ └── error-handling.md # Error handling patterns
22+
├── architecture/ # Detailed architecture documents
23+
│ ├── data-layer.md # ObjectQL architecture
24+
│ ├── ui-layer.md # ObjectUI architecture
25+
│ └── system-layer.md # ObjectOS architecture
26+
└── migration/ # Migration and upgrade guides
27+
├── v0-to-v1.md # Version migration guides
28+
└── breaking-changes.md # Breaking change documentation
29+
```
30+
31+
## 🎯 Quick Navigation
32+
33+
### For Developers
34+
35+
| I want to... | Read this |
36+
|--------------|-----------|
37+
| **Integrate AI features** | [AI Integration Guide](./AI_INTEGRATION_GUIDE.md) |
38+
| **Implement authentication** | [Authentication Standard](./AUTHENTICATION_STANDARD.md) |
39+
| **Understand naming rules** | [Naming Conventions](../CONTRIBUTING.md#naming-conventions) |
40+
| **Learn the architecture** | [Architecture](../ARCHITECTURE.md) |
41+
42+
### For Contributors
43+
44+
| I want to... | Read this |
45+
|--------------|-----------|
46+
| **Start contributing** | [CONTRIBUTING.md](../CONTRIBUTING.md) |
47+
| **See what to work on** | [PRIORITIES.md](../PRIORITIES.md) |
48+
| **Understand the roadmap** | [DEVELOPMENT_ROADMAP.md](../DEVELOPMENT_ROADMAP.md) |
49+
50+
### For Architects
51+
52+
| I want to... | Read this |
53+
|--------------|-----------|
54+
| **System design** | [ARCHITECTURE.md](../ARCHITECTURE.md) |
55+
| **Protocol specifications** | [content/docs/specifications/](../content/docs/specifications/) |
56+
| **Reference documentation** | [content/docs/references/](../content/docs/references/) |
57+
58+
## 📖 Main Documentation Site
59+
60+
The official user-facing documentation is built with Fumadocs and located in:
61+
62+
- **Content**: [`content/docs/`](../content/docs/) - MDX documentation files
63+
- **Site**: [`apps/docs/`](../apps/docs/) - Fumadocs Next.js application
64+
- **Local Preview**: Run `pnpm docs:dev` and visit http://localhost:3000/docs
65+
66+
### Documentation Categories
67+
68+
#### 1. **Concepts** (`content/docs/concepts/`)
69+
High-level explanations and philosophy:
70+
- Architecture overview
71+
- Core values and manifesto
72+
- Enterprise patterns
73+
- Security architecture
74+
- Terminology
75+
76+
#### 2. **Guides** (`content/docs/guides/`)
77+
Step-by-step tutorials and how-tos:
78+
- Getting started
79+
- Installation
80+
- Project structure
81+
- Field types
82+
- Custom drivers
83+
- View configuration
84+
- Workflows and validation
85+
86+
#### 3. **References** (`content/docs/references/`)
87+
API documentation (auto-generated from schemas):
88+
- AI Protocol APIs
89+
- Data Protocol APIs
90+
- System Protocol APIs
91+
- UI Protocol APIs
92+
- API Protocol envelopes and requests
93+
94+
#### 4. **Specifications** (`content/docs/specifications/`)
95+
Detailed protocol specifications:
96+
- Data layer specifications
97+
- UI layer specifications
98+
- Server specifications
99+
- REST API specification
100+
101+
## 🛠️ Technical Guides (This Directory)
102+
103+
### Current Guides
104+
105+
1. **[AI_INTEGRATION_GUIDE.md](./AI_INTEGRATION_GUIDE.md)**
106+
- Building AI-powered applications
107+
- RAG pipeline implementation
108+
- Natural language query processing
109+
- Model registry usage
110+
111+
2. **[AUTHENTICATION_STANDARD.md](./AUTHENTICATION_STANDARD.md)**
112+
- Authentication provider implementation
113+
- OAuth, SAML, LDAP integration
114+
- Session management
115+
- Security best practices
116+
117+
## 📝 Documentation Standards
118+
119+
### Writing Style
120+
121+
- **Clear and Concise** - Use simple language
122+
- **Code Examples** - Provide working examples
123+
- **Progressive Disclosure** - Start simple, then show advanced
124+
- **Bilingual** - Provide EN and CN versions where possible
125+
126+
### Markdown Formatting
127+
128+
```markdown
129+
# Main Title
130+
131+
> Brief description or tagline
132+
133+
## Section
134+
135+
Brief introduction to the section.
136+
137+
### Subsection
138+
139+
Detailed content.
140+
141+
#### Code Examples
142+
143+
\`\`\`typescript
144+
// Always include comments
145+
const example = {
146+
property: 'value',
147+
};
148+
\`\`\`
149+
150+
#### Tips
151+
152+
> 💡 **Tip**: Helpful information for users
153+
154+
#### Warnings
155+
156+
> ⚠️ **Warning**: Important cautionary information
157+
158+
#### Best Practices
159+
160+
> ✅ **Best Practice**: Recommended approach
161+
```
162+
163+
### Code Block Guidelines
164+
165+
1. **Always specify language** for syntax highlighting
166+
2. **Include comments** explaining key parts
167+
3. **Show imports** when relevant
168+
4. **Demonstrate both simple and advanced** usage
169+
5. **Use real-world examples** when possible
170+
171+
### Cross-References
172+
173+
Use relative links to reference other documentation:
174+
175+
```markdown
176+
See [ARCHITECTURE.md](../ARCHITECTURE.md) for system design details.
177+
```
178+
179+
## 🌍 Multilingual Support
180+
181+
### Chinese Documentation
182+
183+
For Chinese versions:
184+
- Create files with `.cn.md` or `.cn.mdx` suffix
185+
- Keep structure identical to English version
186+
- Update `meta.cn.json` for navigation
187+
188+
Example:
189+
```
190+
guides/
191+
├── getting-started.mdx # English
192+
├── getting-started.cn.mdx # Chinese
193+
├── meta.json # English navigation
194+
└── meta.cn.json # Chinese navigation
195+
```
196+
197+
## 🔄 Documentation Workflow
198+
199+
### Adding New Documentation
200+
201+
1. **Identify Category** - Concept, Guide, Reference, or Specification?
202+
2. **Create File** - Use appropriate directory and naming
203+
3. **Follow Template** - Use consistent structure
204+
4. **Add Examples** - Include working code examples
205+
5. **Update Navigation** - Add to `meta.json`
206+
6. **Test Locally** - Run `pnpm docs:dev` to preview
207+
7. **Submit PR** - Follow [CONTRIBUTING.md](../CONTRIBUTING.md)
208+
209+
### Updating Existing Documentation
210+
211+
1. **Make Changes** - Update content
212+
2. **Verify Examples** - Ensure code still works
213+
3. **Update Version** - Note changes in commit message
214+
4. **Test Build** - Run `pnpm docs:build`
215+
5. **Submit PR** - Include "docs:" prefix in commit
216+
217+
## 🧪 Testing Documentation
218+
219+
### Local Testing
220+
221+
```bash
222+
# Start development server
223+
pnpm docs:dev
224+
225+
# Build production site
226+
pnpm docs:build
227+
228+
# Serve production build
229+
pnpm docs:start
230+
```
231+
232+
### Verification Checklist
233+
234+
- [ ] All links work (no 404s)
235+
- [ ] Code examples are syntactically correct
236+
- [ ] Images load properly
237+
- [ ] Navigation is correct
238+
- [ ] Search finds relevant content
239+
- [ ] Build completes without errors
240+
241+
## 📊 Documentation Metrics
242+
243+
### Current Status
244+
245+
- **Concept Pages**: 10+ pages
246+
- **Guides**: 8+ tutorials
247+
- **References**: 250+ API docs
248+
- **Specifications**: 25+ specs
249+
- **Languages**: English, Chinese
250+
- **Total Pages**: 290+
251+
252+
### Coverage Goals
253+
254+
- **Protocol Coverage**: 95%+ (all schemas documented)
255+
- **Examples**: 100%+ working examples
256+
- **Bilingual**: 80%+ pages in both EN/CN
257+
- **Up-to-date**: Review quarterly
258+
259+
## 🤝 Contributing to Documentation
260+
261+
### What We Need
262+
263+
- **More Guides** - Step-by-step tutorials
264+
- **Use Cases** - Real-world examples
265+
- **Translations** - Chinese translations
266+
- **Diagrams** - Architecture visualizations
267+
- **Videos** - Screencasts and tutorials
268+
269+
### How to Help
270+
271+
1. **Report Issues** - Found unclear docs? Open an issue
272+
2. **Suggest Improvements** - Have ideas? Create a discussion
273+
3. **Submit Changes** - Fix typos, improve examples
274+
4. **Write New Content** - Add guides, examples
275+
276+
See [CONTRIBUTING.md](../CONTRIBUTING.md) for detailed guidelines.
277+
278+
## 📞 Getting Help
279+
280+
### Documentation Questions
281+
282+
- **GitHub Discussions** - Ask questions about documentation
283+
- **GitHub Issues** - Report documentation bugs
284+
- **Pull Requests** - Suggest documentation improvements
285+
286+
### Documentation Team
287+
288+
- Review [PLANNING_INDEX.md](../PLANNING_INDEX.md) for planning docs
289+
- Check [DEVELOPMENT_ROADMAP.md](../DEVELOPMENT_ROADMAP.md) for documentation roadmap
290+
291+
## 📄 License
292+
293+
Documentation is licensed under [Apache 2.0](../LICENSE).
294+
295+
---
296+
297+
**Last Updated**: 2026-01-22
298+
**Maintainer**: ObjectStack Documentation Team
299+
**Status**: ✅ Active

0 commit comments

Comments
 (0)