|
1 | | -# AI-Driven Project Structure |
| 1 | +# Project Structure |
2 | 2 |
|
3 | | -This document defines the directory structure designed to facilitate AI-driven development. The goal is to establish a deterministic 1:1 mapping between the ObjectQL specifications (in `docs/objectql`) and the source code. |
| 3 | +This document defines the current directory structure of Object UI, designed for clarity and AI-driven development. |
4 | 4 |
|
5 | 5 | ## 1. Top-Level Structure (Monorepo) |
6 | 6 |
|
7 | 7 | We use a standard Monorepo structure managed by `pnpm`. |
8 | 8 |
|
9 | 9 | ``` |
10 | 10 | / |
11 | | -├── apps/ # End-user applications |
12 | | -│ ├── design-studio/ # The visual designer (Next.js/Vite) |
13 | | -│ └── docs/ # Documentation site |
14 | | -├── packages/ # Shared libraries |
15 | | -│ ├── protocol/ # (New) Pure Metadata Definitions & Types |
16 | | -│ ├── engine/ # (New) The Core Logic (State, Data, Expressions) |
17 | | -│ ├── ui/ # (New) The Atomic Component Library (Shadcn + Tailwind) |
18 | | -│ └── renderer/ # (Renamed from react) The Schema->React Transformer |
19 | | -├── docs/ |
20 | | -│ ├── objectql/ # The Source of Truth (Specs) |
21 | | -│ └── spec/ # Technical Specs |
| 11 | +├── examples/ # Example applications |
| 12 | +│ ├── prototype/ # Main prototype/demo app |
| 13 | +│ └── designer-demo/ # Designer demonstration |
| 14 | +├── packages/ # Shared libraries |
| 15 | +│ ├── core/ # Core logic, types, and validation (Zero React) |
| 16 | +│ ├── react/ # React bindings and SchemaRenderer |
| 17 | +│ ├── components/ # Standard UI components (Shadcn + Tailwind) |
| 18 | +│ └── designer/ # Visual schema editor |
| 19 | +├── docs/ # Documentation site (VitePress) |
| 20 | +│ ├── .vitepress/ # VitePress configuration |
| 21 | +│ ├── guide/ # User guides |
| 22 | +│ ├── api/ # API documentation |
| 23 | +│ ├── protocol/ # Protocol specifications |
| 24 | +│ └── spec/ # Technical specifications |
| 25 | +└── .github/ # GitHub workflows and configurations |
22 | 26 | ``` |
23 | 27 |
|
24 | 28 | ## 2. Package Responsibilities |
25 | 29 |
|
26 | | -### `@object-ui/protocol` (was `core`) |
27 | | -**Goal**: Define the "Language" of ObjectQL. |
28 | | -**Mapping**: `docs/objectql/*.md` → `packages/protocol/src/*.ts` |
| 30 | +### `@object-ui/core` |
| 31 | +**Goal**: The "Brain" - Core logic with zero React dependencies. |
| 32 | +**Tech**: Pure TypeScript + Zod + Lodash |
29 | 33 |
|
30 | | -* `src/types/object.ts` (Defines ObjectConfig) |
31 | | -* `src/types/field.ts` (Defines FieldConfig) |
32 | | -* `src/types/view.ts` (Defines ViewConfig) |
33 | | -* `src/types/page.ts` (Defines PageConfig) |
34 | | -* `src/utils/validator.ts` (Zod schemas for runtime validation) |
| 34 | +**Contents**: |
| 35 | +- `src/types/` - TypeScript type definitions (schemas, components) |
| 36 | +- `src/registry/` - Component registry system |
| 37 | +- `src/data-scope/` - Data scope and expression evaluation |
| 38 | +- `src/validators/` - Zod validation schemas |
35 | 39 |
|
36 | | -### `@object-ui/engine` (was `react` internals) |
37 | | -**Goal**: The "Brain". Headless logic for handling data. |
| 40 | +**Key Principle**: This package can run in Node.js or any JavaScript environment. |
38 | 41 |
|
39 | | -* `src/store/` (Zustand stores for Object data) |
40 | | -* `src/data-source/` (React Query wrappers) |
41 | | -* `src/expressions/` (Expression evaluator) |
42 | | -* `src/context/` (DataScope implementation) |
| 42 | +### `@object-ui/react` |
| 43 | +**Goal**: The "Glue" - React bindings and renderer. |
| 44 | +**Tech**: React 18+ with Hooks |
43 | 45 |
|
44 | | -### `@object-ui/ui` (was `components`) |
45 | | -**Goal**: The "Look". Dumb, stateless UI atoms. |
46 | | -**Tech**: Radix UI + Tailwind + Shadcn. |
47 | | - |
48 | | -* `src/primitives/` (Button, Input, Dialog) |
49 | | -* `src/layout/` (Grid, Stack, Card) |
| 46 | +**Structure**: |
| 47 | +``` |
| 48 | +src/ |
| 49 | +├── SchemaRenderer.tsx # Main renderer component |
| 50 | +├── hooks/ # React hooks |
| 51 | +│ ├── useRenderer.ts |
| 52 | +│ ├── useDataScope.ts |
| 53 | +│ └── useRegistry.ts |
| 54 | +└── context/ # React Context providers |
| 55 | + ├── RendererContext.tsx |
| 56 | + └── DataScopeContext.tsx |
| 57 | +``` |
50 | 58 |
|
51 | | -### `@object-ui/renderer` (was `react` public) |
52 | | -**Goal**: The "Compiler". Turns Metadata into UI. |
53 | | -**Structure**: Strictly organized by Schema Type. |
| 59 | +### `@object-ui/components` |
| 60 | +**Goal**: The "Body" - Standard UI implementation. |
| 61 | +**Tech**: Shadcn UI + Radix UI + Tailwind CSS |
54 | 62 |
|
| 63 | +**Structure**: |
55 | 64 | ``` |
56 | 65 | src/ |
57 | | -├── renderers/ |
58 | | -│ ├── page/ |
59 | | -│ │ ├── PageRenderer.tsx |
60 | | -│ │ └── index.ts |
61 | | -│ ├── object/ |
62 | | -│ │ ├── ObjectFormRenderer.tsx |
63 | | -│ │ ├── ObjectTableRenderer.tsx |
64 | | -│ │ └── ... |
65 | | -│ ├── view/ |
66 | | -│ │ ├── ViewRenderer.tsx (Dispatcher) |
67 | | -│ │ ├── ListView.tsx |
68 | | -│ │ ├── KanbanView.tsx |
69 | | -│ │ └── ... |
70 | | -│ └── field/ |
71 | | -│ ├── FieldRenderer.tsx (Dispatcher) |
72 | | -│ ├── StringField.tsx |
73 | | -│ └── SelectField.tsx |
74 | | -├── registry.ts # Maps types to renderers |
75 | | -└── SchemaRenderer.tsx # Entry point |
| 66 | +├── ui/ # Base Shadcn components |
| 67 | +│ ├── button.tsx |
| 68 | +│ ├── input.tsx |
| 69 | +│ ├── select.tsx |
| 70 | +│ └── ... |
| 71 | +├── renderers/ # Object UI component renderers |
| 72 | +│ ├── basic/ # Basic components |
| 73 | +│ ├── form/ # Form components |
| 74 | +│ ├── layout/ # Layout components |
| 75 | +│ └── data-display/ # Data display components |
| 76 | +└── index.ts # Public exports |
| 77 | +``` |
| 78 | + |
| 79 | +### `@object-ui/designer` |
| 80 | +**Goal**: The "Tool" - Visual schema editor. |
| 81 | +**Tech**: React + Drag-and-Drop |
| 82 | + |
| 83 | +**Contents**: |
| 84 | +- `src/Designer.tsx` - Main designer component |
| 85 | +- `src/Canvas.tsx` - Visual editing canvas |
| 86 | +- `src/ComponentPalette.tsx` - Component library browser |
| 87 | +- `src/PropertyPanel.tsx` - Property editor |
| 88 | +- `src/Toolbar.tsx` - Actions toolbar |
| 89 | +- `src/context/` - Designer state management |
| 90 | + |
| 91 | +## 3. Development Workflow |
| 92 | + |
| 93 | +### Adding a New Component |
| 94 | + |
| 95 | +When implementing a new component: |
| 96 | + |
| 97 | +1. **Define Types** in `packages/core/src/types/` |
| 98 | + ```typescript |
| 99 | + export interface MyComponentSchema extends BaseSchema { |
| 100 | + type: 'my-component' |
| 101 | + // ... component-specific properties |
| 102 | + } |
| 103 | + ``` |
| 104 | + |
| 105 | +2. **Create UI Component** in `packages/components/src/ui/` (if needed) |
| 106 | + ```tsx |
| 107 | + // Base Shadcn component |
| 108 | + export function MyComponent({ ... }) { ... } |
| 109 | + ``` |
| 110 | + |
| 111 | +3. **Create Renderer** in `packages/components/src/renderers/` |
| 112 | + ```tsx |
| 113 | + export function MyComponentRenderer({ schema, ...props }) { |
| 114 | + return <MyComponent {...props} {...schema} /> |
| 115 | + } |
| 116 | + ``` |
| 117 | + |
| 118 | +4. **Register** in `packages/components/src/index.ts` |
| 119 | + ```typescript |
| 120 | + registry.register('my-component', MyComponentRenderer) |
| 121 | + ``` |
| 122 | + |
| 123 | +### Package Dependencies |
| 124 | + |
| 125 | +``` |
| 126 | +designer |
| 127 | + ↓ |
| 128 | +components ──→ react ──→ core |
| 129 | + ↓ ↓ |
| 130 | +ui components types & logic |
76 | 131 | ``` |
77 | 132 |
|
78 | | -## 3. Workflow for AI |
| 133 | +**Dependency Rules**: |
| 134 | +- `core`: NO dependencies on React or any UI framework |
| 135 | +- `react`: Depends on `core`, peer depends on React |
| 136 | +- `components`: Depends on `core` + `react` + Shadcn/Radix |
| 137 | +- `designer`: Depends on `components` |
79 | 138 |
|
80 | | -When asked to "Implement the View spec": |
| 139 | +## 4. File Naming Conventions |
81 | 140 |
|
82 | | -1. **Read** `docs/objectql/view.md`. |
83 | | -2. **Define** `packages/protocol/src/types/view.ts`. |
84 | | -3. **Create** `packages/renderer/src/renderers/view/ViewRenderer.tsx`. |
85 | | -4. **Register** it in `packages/renderer/src/registry.ts`. |
| 141 | +- **Components**: PascalCase with `.tsx` extension (e.g., `Button.tsx`) |
| 142 | +- **Hooks**: camelCase starting with `use` (e.g., `useRenderer.ts`) |
| 143 | +- **Types**: PascalCase with `.ts` extension (e.g., `Schema.ts`) |
| 144 | +- **Utilities**: camelCase with `.ts` extension (e.g., `registry.ts`) |
| 145 | + |
| 146 | +## 5. Import Aliases |
| 147 | + |
| 148 | +When working within the monorepo, use workspace protocol: |
| 149 | + |
| 150 | +```typescript |
| 151 | +// In packages/react |
| 152 | +import { BaseSchema } from '@object-ui/core' |
| 153 | + |
| 154 | +// In packages/components |
| 155 | +import { SchemaRenderer } from '@object-ui/react' |
| 156 | +import type { ButtonSchema } from '@object-ui/core' |
| 157 | +``` |
0 commit comments