Add initial project files

2026-09-01 13:03:41 +03:00
parent 22e111bb44
commit 74cb5b6176
1841 changed files with 242819 additions and 30 deletions
@@ -0,0 +1,82 @@
+# 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. **Гнучкість допускається**.
+   - Ви можете коригувати шари, структуру модулів або угоди щодо найменування, якщо це покращує читабельність або зменшує складність.
+   - У міру розвитку проєкту можна додавати нові патерни або винятки.
+
+Коротко: цей посібник існує для того, щоб проєкт був зрозумілішим і простішим у підтримці, а не для того, щоб створювати зайві труднощі. Керуйтеся здоровим глуздом і надавайте перевагу ясності, а не жорсткій послідовності.