83 lines
6.7 KiB
Markdown
83 lines
6.7 KiB
Markdown
# CRUX React Admin Panel Architecture
|
||
|
||
## Core Principles
|
||
|
||
1. **Blocks are composable and isolated** — each block (component, form, widget) has a single responsibility; higher-level blocks (widgets, pages) compose lower-level ones.
|
||
2. **Data vs. UI separation** — `data` handles API, state, and business data; `view` handles UI and interaction. No API logic in UI components — UI calls hooks from `data`.
|
||
3. **Entities are global types** — placed in `entities/`, usable by any block.
|
||
4. **Shared** — `shared/` = globally reusable components, hooks, utilities.
|
||
5. **Infrastructure** — `infrastructure/` = app-wide technical adapters: HTTP clients, React Query, storage adapters, formatting service wrappers.
|
||
6. **Reference data** — `refdata/` = app-wide API-backed lookup datasets shared by multiple modules.
|
||
|
||
## Recommended Layering
|
||
|
||
```plaintext
|
||
src/
|
||
├── app/ # composition root: providers, routing, config, i18n, layouts
|
||
├── infrastructure/ # technical adapters: HTTP, query, storage, error handling
|
||
├── refdata/ # API-backed common reference datasets
|
||
├── shared/ # reusable app-wide UI, hooks, utilities, and widgets
|
||
├── core/ # built-in product modules
|
||
├── modules/ # project-specific modules
|
||
└── devtools/ # development-only modules and tools
|
||
```
|
||
|
||
## Architecture Scope
|
||
|
||
The layer structure can be used at three levels:
|
||
|
||
| Scope | Example | Meaning |
|
||
| --------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| App-level architecture | `apps/admin/src/app`, `apps/admin/src/shared` | Global app shell, providers, routing, layout, infrastructure, reusable app-wide building blocks. |
|
||
| Core module architecture | `apps/admin/src/core/FileManager` | Built-in product modules shipped with the admin template. Each large core module can own its own `data`, `entities`, `pages`, `view`, and `shared`, plus feature-scoped context when needed. |
|
||
| Project module architecture | `apps/admin/src/modules/*` | Generated or project-specific modules. Each module should follow the same layer rules inside its own folder when it becomes more than a simple page. |
|
||
|
||
For small modules, do not create empty layers only to match the template. Add a layer when the module has real ownership for that layer.
|
||
|
||
## Full documentation
|
||
|
||
- [Entities Layer](./layers/entities.md)
|
||
- [Data Layer](./layers/data.md)
|
||
- [App Layer](./layers/app.md)
|
||
- [Infrastructure Layer](./layers/infrastructure.md)
|
||
- [Reference Data Layer](./layers/refdata.md)
|
||
- [View Layer](./layers/view.md)
|
||
- [Shared Layer](./layers/shared.md)
|
||
- [File & Folder Naming Convention](./naming.md)
|
||
|
||
## Disclaimer
|
||
|
||
This architecture guide is intended as a **recommendation**, not a strict rulebook. **Feel free to adapt and modify it based on your team’s needs and project context**.
|
||
|
||
Key points to keep in mind:
|
||
|
||
1. **Maintainability comes first**.
|
||
The main goal of this structure is to help someone new to the project quickly understand where to make changes.
|
||
It’s about finding the right place to touch the code now, rather than strictly following a pattern for its own sake.
|
||
**Ultimately, the main goal is to make development easier for everyone**
|
||
2. **Naming debates are inevitable**.
|
||
Any architecture guide may spark discussions about file, folder, or function naming. Use this guide as a reference, but remember that practicality and clarity are more important than strict adherence.
|
||
3. **Flexibility is allowed**.
|
||
- You can adjust layers, module structure, or naming conventions if it improves readability or reduces complexity.
|
||
- New patterns or exceptions can be added as the project evolves.
|
||
|
||
In short: this guide exists to make the project easier to understand and maintain, not to create unnecessary friction. Use judgment and prioritize clarity over rigid consistency.
|
||
|
||
---
|
||
|
||
Цей посібник з архітектури є **рекомендацією**, а не суворим зводом правил. **Не соромтеся адаптувати та змінювати його відповідно до потреб вашої команди та контексту проєкту**.
|
||
|
||
Ключові моменти, які варто мати на увазі:
|
||
|
||
1. **Насамперед — зручність підтримки**.
|
||
Головна мета цієї структури — допомогти новому учаснику проєкту швидко зрозуміти, де вносити зміни.
|
||
Йдеться про те, щоб знайти правильне місце в коді просто зараз, а не сліпо дотримуватися патерну заради самого патерну.
|
||
**Зрештою, головна мета — зробити розробку простішою для всіх.**
|
||
2. **Дискусії щодо назв неминучі**.
|
||
Будь-який посібник з архітектури може спровокувати суперечки щодо назв файлів, папок або функцій. Використовуйте цей посібник як орієнтир, але пам'ятайте, що практичність і зрозумілість важливіші за суворе дотримання правил.
|
||
3. **Гнучкість допускається**.
|
||
- Ви можете коригувати шари, структуру модулів або угоди щодо найменування, якщо це покращує читабельність або зменшує складність.
|
||
- У міру розвитку проєкту можна додавати нові патерни або винятки.
|
||
|
||
Коротко: цей посібник існує для того, щоб проєкт був зрозумілішим і простішим у підтримці, а не для того, щоб створювати зайві труднощі. Керуйтеся здоровим глуздом і надавайте перевагу ясності, а не жорсткій послідовності.
|