# samiulislamramim/sportigy-arbree architecture

> Architecture diagram of the GitHub repository samiulislamramim/sportigy-arbree, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samiulislamramim/sportigy-arbree
- Repository: https://github.com/samiulislamramim/sportigy-arbree

## Overview

1. **Overall shape**
   - This is a **Next.js 15 + TypeScript** scaffold built around a reusable UI/component library rather than a domain-specific backend.
   - The repository is organized as a **presentation-first frontend**: routes live in `src/app`, while reusable behavior is factored into `components`, `hooks`, `store`, `api`, and `providers`.

2. **Route layer: App Router entry points**
   - `src/app` is the navigation boundary for the app.
   - It contains the root layout and app-level states (`layout.tsx`, `loading.tsx`, `error.tsx`, `not-found.tsx`) plus a home page and an `examples` section.
   - The `examples` subtree is important: it acts as a **demo surface** for the reusable form, dialog, and table patterns rather than a business workflow.

3. **Page-to-container pattern**
   - Route files are thin and delegate to container components like `home-container.tsx`, `examples-container.tsx`, `dialog-container.tsx`, `form-container.tsx`, and `table-container.tsx`.
   - This suggests a boundary where **routing concerns stay in `app/`** and **feature composition lives in containers** under `src/app/...` or `components/...`.

4. **Reusable UI subsystem**
   - `src/components/ui` contains the base design-system primitives: button, input, select, dialog, table, tabs, tooltip, sheet, etc.
   - These are the lowest-level visual building blocks, likely shadcn-generated wrappers over Radix-style primitives.
   - Higher-level components should be composed from these primitives rather than directly from route code.

5. **Common application components**
   - `src/components/common` holds app-wide reusable widgets: navbar, app shell, theme toggle, pagination, toast, action button, dialog wrapper, and the dynamic table.
   - The `fields` subtree is a major subsystem: it provides many specialized input controls for forms, including date pickers, uploads, OTP, rich text, multi-select, phone number, range date, and more.
   - This makes the repo more of a **component toolkit** with form-heavy capabilities than a simple page app.

6. **Form subsystem**
   - Form handling is centered in `src/forms/react-hook-form`, with a custom hook (`use-form.hook.ts`) and example schema(s).
   - `src/components/forms/login-form.component.tsx` likely demonstrates how `react-hook-form` integrates with the shared field components.
   - The architecture implies a separation between **schema/form logic** and **field rendering widgets**.

7. **State management boundary**
   - Global state is managed with **zustand** under `src/store/zustand`.
   - The included stores (`counter.store.ts`, `user.store.ts`) look like example or starter stores, reinforcing that the repo is scaffolded and extensible.
   - State usage is likely client-side and localized to components rather than centralized app-wide data orchestration.

8. **Data access layer**
   - `src/api/fetch` is the API boundary, using the native **fetch** API rather than a heavier client.
   - The presence of `client.api.ts` and `users.api.ts` suggests a simple split between shared fetch/client setup and resource-specific endpoints.
   - This layer is separate from UI and stores, which keeps remote data access isolated for future expansion.

9. **Cross-cutting client hooks**
   - `src/hooks` contains generic React hooks for debounce, fetch, intersection observer, local storage, media query, and toggle behavior.
   - These hooks are infrastructure for the UI layer, enabling reusable behavior without embedding logic in components.
   - Several of them support common frontend concerns like responsiveness, persistence, and async loading.

10. **Providers and app-wide context**
   - `src/providers` wraps application-level concerns such as theme and toast messaging.
   - `toast.provider.tsx` and `theme.provider.tsx` indicate that the root app layout likely composes provider boundaries around the page tree.
   - This is where the app’s **global client context** is introduced before route content renders.

11. **Styling and utility layer**
   - `tailwind.config.ts`, `postcss.config.mjs`, and `src/app/globals.css` define the styling pipeline.
   - `src/lib/utils.util.ts` is the shared utility layer, likely used by UI primitives and composition helpers.
   - The architecture depends on Tailwind for styling consistency and utility-driven composition.

12. **Scripts and repo hygiene**
   - `scripts/cleanup.mjs` is a notable maintenance tool: it removes demo/example code when the scaffold is turned into a real product.
   - That reinforces the repo’s role as a **starter architecture** with built-in demo surfaces and a cleanup path.

13. **External/runtime boundaries**
   - The documented runtime stack is purely frontend: **Next.js, React, TypeScript, shadcn UI, zustand, react-hook-form, fetch**.
   - There is no auth subsystem and no dedicated backend service layer in this repo, so the main architecture boundary is between **UI/client state** and **HTTP fetch calls**.

14. **How data typically flows**
   - A route renders a page/container, the container composes common and UI components, those components use hooks/providers/store as needed, and remote data is pulled through the fetch API layer.
   - Forms flow in the opposite direction: field components feed `react-hook-form`, which validates via schemas and then submits through UI actions or API calls.

Main entry points: [`src/components/common/navbar.component.tsx`](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/common/navbar.component.tsx) (Common widgets), [`src/components/ui/button.component.tsx`](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/ui/button.component.tsx) (UI primitives), [`src/app/layout.tsx`](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/layout.tsx) (Root app), [`src/components/common/fields/cusInputField.component.tsx`](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/common/fields/cusInputField.component.tsx) (Field system)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_app["App Router"]
  node_n_app_root["Root app<br/>next layout<br/>[layout.tsx]"]
  node_n_app_home["Home page<br/>route<br/>[page.tsx]"]
  node_n_app_home_container["Home container<br/>page container<br/>[home-container.tsx]"]
  node_n_app_examples["Examples area<br/>demo routes<br/>[page.tsx]"]
  node_n_app_examples_container["Examples container<br/>page container"]
  node_n_app_examples_form["Form demo<br/>route<br/>[page.tsx]"]
  node_n_app_examples_form_container["Form container<br/>page container<br/>[form-container.tsx]"]
  node_n_app_examples_dialog["Dialog demo<br/>route<br/>[page.tsx]"]
  node_n_app_examples_dialog_container["Dialog container<br/>page container"]
  node_n_app_examples_table["Table demo<br/>route<br/>[page.tsx]"]
  node_n_app_examples_table_container["Table container<br/>page container"]
end

subgraph group_g_components["UI System"]
  node_n_ui_primitives["UI primitives<br/>design system"]
  node_n_common_shell["App shell<br/>common chrome"]
  node_n_common_widgets["Common widgets<br/>shared UI"]
  node_n_common_fields["Field system<br/>form widgets"]
  node_n_common_dynamic_table["Dynamic table<br/>table widget"]
  node_n_login_form["Login form<br/>form composition"]
  node_n_form_runtime["RHF runtime<br/>form infrastructure<br/>[use-form.hook.ts]"]
end

subgraph group_g_data["Data & State"]
  node_n_fetch_api["Fetch API<br/>data access<br/>[client.api.ts]"]
  node_n_zustand_store["Zustand store<br/>client state<br/>[index.ts]"]
  node_n_hooks["React hooks<br/>client hooks<br/>[use-fetch.hook.ts]"]
end

subgraph group_g_platform["Platform"]
  node_n_providers["Providers<br/>context shell<br/>[index.tsx]"]
  node_n_utils["Shared utils<br/>utility layer<br/>[utils.util.ts]"]
  node_n_styles["Styling<br/>tailwind css<br/>[globals.css]"]
  node_n_cleanup["Cleanup script<br/>maintenance<br/>[cleanup.mjs]"]
end

node_n_app_root -->|"wraps"| node_n_providers
node_n_app_root -->|"uses"| node_n_common_shell
node_n_app_root -->|"loads"| node_n_styles
node_n_app_home -->|"delegates"| node_n_app_home_container
node_n_app_examples -->|"delegates"| node_n_app_examples_container
node_n_app_examples_form -->|"delegates"| node_n_app_examples_form_container
node_n_app_examples_dialog -->|"delegates"| node_n_app_examples_dialog_container
node_n_app_examples_table -->|"delegates"| node_n_app_examples_table_container
node_n_app_examples_container -->|"composes"| node_n_login_form
node_n_app_examples_form_container -->|"composes"| node_n_common_fields
node_n_app_examples_dialog_container -->|"composes"| node_n_common_widgets
node_n_app_examples_table_container -->|"composes"| node_n_common_dynamic_table
node_n_login_form -->|"binds"| node_n_form_runtime
node_n_common_fields -->|"wraps"| node_n_ui_primitives
node_n_common_widgets -->|"wraps"| node_n_ui_primitives
node_n_common_dynamic_table -->|"wraps"| node_n_ui_primitives
node_n_common_shell -->|"contains"| node_n_common_widgets
node_n_common_widgets -->|"uses"| node_n_hooks
node_n_common_fields -->|"uses"| node_n_hooks
node_n_fetch_api -->|"used by"| node_n_hooks
node_n_zustand_store -->|"feeds"| node_n_common_widgets
node_n_providers -->|"supports"| node_n_common_widgets
node_n_ui_primitives -->|"uses"| node_n_utils
node_n_cleanup -.->|"targets"| node_n_app_examples

click node_n_app_root "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/layout.tsx"
click node_n_app_home "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/page.tsx"
click node_n_app_home_container "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/home-container.tsx"
click node_n_app_examples "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/page.tsx"
click node_n_app_examples_container "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/examples-container.tsx"
click node_n_app_examples_form "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/form/page.tsx"
click node_n_app_examples_form_container "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/form/form-container.tsx"
click node_n_app_examples_dialog "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/dialog/page.tsx"
click node_n_app_examples_dialog_container "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/dialog/dialog-container.tsx"
click node_n_app_examples_table "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/table/page.tsx"
click node_n_app_examples_table_container "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/table/table-container.tsx"
click node_n_ui_primitives "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/ui/button.component.tsx"
click node_n_common_shell "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/common/app-shell.component.tsx"
click node_n_common_widgets "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/common/navbar.component.tsx"
click node_n_common_fields "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/common/fields/cusInputField.component.tsx"
click node_n_common_dynamic_table "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/common/DynamicTable/dynamic-table.component.tsx"
click node_n_login_form "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/forms/login-form.component.tsx"
click node_n_form_runtime "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/forms/react-hook-form/hooks/use-form.hook.ts"
click node_n_fetch_api "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/api/fetch/client.api.ts"
click node_n_zustand_store "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/store/zustand/index.ts"
click node_n_hooks "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/hooks/use-fetch.hook.ts"
click node_n_providers "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/providers/index.tsx"
click node_n_utils "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/lib/utils.util.ts"
click node_n_styles "https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/globals.css"
click node_n_cleanup "https://github.com/samiulislamramim/sportigy-arbree/blob/main/scripts/cleanup.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_app_root,node_n_app_home,node_n_app_home_container,node_n_app_examples,node_n_app_examples_container,node_n_app_examples_form,node_n_app_examples_form_container,node_n_app_examples_dialog,node_n_app_examples_dialog_container,node_n_app_examples_table,node_n_app_examples_table_container toneBlue
class node_n_ui_primitives,node_n_common_shell,node_n_common_widgets,node_n_common_fields,node_n_common_dynamic_table,node_n_login_form,node_n_form_runtime toneAmber
class node_n_fetch_api,node_n_zustand_store,node_n_hooks toneMint
class node_n_providers,node_n_utils,node_n_styles,node_n_cleanup toneRose
```

## Components

### App Router

Route entry points, layouts, and demo pages.

- [Root app](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/layout.tsx): next layout · App Router shell and global route boundaries. · `src/app/layout.tsx`
- [Home page](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/page.tsx): route · Main landing route wired through a thin container. · `src/app/page.tsx`
- [Home container](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/home-container.tsx): page container · Composes the home surface outside the route file. · `src/app/home-container.tsx`
- [Examples area](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/page.tsx): demo routes · Demo surface for form, dialog, and table patterns. · `src/app/examples/page.tsx`
- [Examples container](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/examples-container.tsx): page container · Shared container for the examples subtree. · `src/app/examples/examples-container.tsx`
- [Form demo](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/form/page.tsx): route · Examples route focused on form composition. · `src/app/examples/form/page.tsx`
- [Form container](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/form/form-container.tsx): page container · Container for the form example. · `src/app/examples/form/form-container.tsx`
- [Dialog demo](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/dialog/page.tsx): route · Examples route focused on dialog composition. · `src/app/examples/dialog/page.tsx`
- [Dialog container](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/dialog/dialog-container.tsx): page container · Container for the dialog example. · `src/app/examples/dialog/dialog-container.tsx`
- [Table demo](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/table/page.tsx): route · Examples route focused on table composition. · `src/app/examples/table/page.tsx`
- [Table container](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/examples/table/table-container.tsx): page container · Container for the table example. · `src/app/examples/table/table-container.tsx`

### UI System

Reusable components, field widgets, and form compositions.

- [UI primitives](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/ui/button.component.tsx): design system · Base visual building blocks such as inputs, dialogs, tables, and tabs. · `src/components/ui/button.component.tsx`
- [App shell](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/common/app-shell.component.tsx): common chrome · Global navigation and layout chrome. · `src/components/common/app-shell.component.tsx`
- [Common widgets](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/common/navbar.component.tsx): shared UI · Reusable app widgets like navbar, pagination, theme toggle, and dialog wrappers. · `src/components/common/navbar.component.tsx`
- [Field system](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/common/fields/cusInputField.component.tsx): form widgets · Specialized input controls for complex forms and uploads. · `src/components/common/fields/cusInputField.component.tsx`
- [Dynamic table](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/common/DynamicTable/dynamic-table.component.tsx): table widget · Higher-level table composition for flexible tabular rendering. · `src/components/common/DynamicTable/dynamic-table.component.tsx`
- [Login form](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/components/forms/login-form.component.tsx): form composition · Example form wiring shared fields into a concrete form. · `src/components/forms/login-form.component.tsx`
- [RHF runtime](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/forms/react-hook-form/hooks/use-form.hook.ts): form infrastructure · Shared react-hook-form hook and schema layer. · `src/forms/react-hook-form/hooks/use-form.hook.ts`

### Data & State

Fetch layer, hooks, and client-side state management.

- [Fetch API](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/api/fetch/client.api.ts): data access · Native fetch boundary and resource-specific API modules. · `src/api/fetch/client.api.ts`
- [Zustand store](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/store/zustand/index.ts): client state · Global client-side state containers for app examples and local UI state. · `src/store/zustand/index.ts`
- [React hooks](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/hooks/use-fetch.hook.ts): client hooks · Reusable behavior for debounce, fetching, media queries, storage, and observers. · `src/hooks/use-fetch.hook.ts`

### Platform

Styling, providers, shared utilities, and maintenance scripts.

- [Providers](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/providers/index.tsx): context shell · Theme and toast context wrappers mounted around the app tree. · `src/providers/index.tsx`
- [Shared utils](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/lib/utils.util.ts): utility layer · Common helpers used across components and composition code. · `src/lib/utils.util.ts`
- [Styling](https://github.com/samiulislamramim/sportigy-arbree/blob/main/src/app/globals.css): tailwind css · Global styling pipeline and app stylesheet. · `src/app/globals.css`
- [Cleanup script](https://github.com/samiulislamramim/sportigy-arbree/blob/main/scripts/cleanup.mjs): maintenance · Removes demo scaffold code when promoting the starter into a product. · `scripts/cleanup.mjs`

## Connections

- Root app → Providers: wraps · Root layout composes application-wide context providers.
- Root app → App shell: uses · Layout-level shell frames route content.
- Root app → Styling: loads · Global stylesheet is applied at app root.
- Home page → Home container: delegates · Route file forwards rendering to the container.
- Examples area → Examples container: delegates · Examples index route delegates to shared container.
- Form demo → Form container: delegates · Form route keeps routing thin.
- Dialog demo → Dialog container: delegates · Dialog route keeps routing thin.
- Table demo → Table container: delegates · Table route keeps routing thin.
- Examples container → Login form: composes · Examples surface showcases the login form composition.
- Form container → Field system: composes · Form demo uses the shared field system.
- Dialog container → Common widgets: composes · Dialog demo uses shared dialog and chrome widgets.
- Table container → Dynamic table: composes · Table demo uses the dynamic table layer.
- Login form → RHF runtime: binds · Concrete form is built on the shared react-hook-form runtime.
- Field system → UI primitives: wraps · Specialized fields are assembled from base UI primitives.
- Common widgets → UI primitives: wraps · Shared widgets are composed from the primitive component set.
- Dynamic table → UI primitives: wraps · Dynamic table builds on the base table primitives.
- App shell → Common widgets: contains · App shell includes shared navigation and chrome widgets.
- Common widgets → React hooks: uses · Widgets rely on reusable client hooks for behavior.
- Field system → React hooks: uses · Field widgets use cross-cutting hooks for input behavior.
- Fetch API → React hooks: used by · Fetching concerns are surfaced through reusable hooks.
- Zustand store → Common widgets: feeds · Client state supports shared interactive widgets.
- Providers → Common widgets: supports · Theme and toast providers back shared UI behavior.
- UI primitives → Shared utils: uses · Primitive components share common helper utilities.
- Cleanup script → Examples area: targets · Cleanup script removes demo/example surfaces.