# saad036/house-build-expense-frontend architecture

> Architecture diagram of the GitHub repository saad036/house-build-expense-frontend, 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/saad036/house-build-expense-frontend
- Repository: https://github.com/saad036/house-build-expense-frontend

## Overview

1. **Project shape**
   - This is a **Create React App** frontend written in **TypeScript**.
   - The app is organized as a classic single-page application with **route-level pages**, shared **layout components**, reusable **UI primitives**, and a **Redux-based state/data layer**.

2. **Top-level presentation flow**
   - `src/index.tsx` bootstraps the app.
   - `src/Routes.tsx` is the main route registry.
   - `src/Layouts` provides the application shell, especially the **sidebar-based navigation**.
   - Page modules under `src/Pages` compose feature-specific view components from `src/Components`.

3. **Route and access control boundary**
   - `src/RoutesProtection` is the main security boundary for the client UI.
   - It likely checks authentication state/token presence before allowing access to protected areas such as **Home**, **Users**, and **Expenses**.
   - Authentication-related utilities live under `src/Utilities/Cookies.ts` and `src/Utilities/Users/UserToken.ts`, which suggests token persistence is cookie-based.

4. **Feature domains**
   - The app is split into three primary business areas:
     - **Auth**: login flow under `src/Pages/Auth/Login`
     - **Users**: create/list users under `src/Components/Users` and `src/Pages/Users`
     - **Expenses**: create/edit/list expenses under `src/Components/Expenses` and `src/Pages/Expenses`
   - `src/Components/Home` is a dashboard layer that summarizes expense data.

5. **Reusable UI system**
   - `src/Components/Custom` is a shared UI library built specifically for this app.
   - It includes:
     - form inputs (`FormTextInput`, `FormSelectInput`, `FormDateInput`, `FormNumberInput`, `FormCurrencyInput`, `FormTextAreaInput`)
     - table, tab, modal, popover, pagination, menu, loading placeholders, avatar, and custom buttons
   - This indicates most feature screens are assembled from standardized internal components rather than using a third-party component framework as the primary abstraction.

6. **Form architecture**
   - `src/Components/Custom/Form` is a distinct form subsystem, with a `FormObserver` and field-level wrappers.
   - This implies forms are likely managed through a shared form state mechanism, with validation and field rendering centralized.
   - Feature modules such as **CreateUser**, **CreateExpense**, **EditExpense**, and **Login** depend on these form primitives.

7. **Redux state and side effects**
   - `src/Redux` is the main application state layer.
   - It contains:
     - **actions** for auth, users, expenses, and general UI state
     - **reducers** for the same domains
     - the centralized store in `store.ts`
     - typed state definitions in `types/`
   - The state model is domain-oriented, with separate slices for **auth**, **users**, **expenses**, and **general** concerns.

8. **API integration layer**
   - API access is abstracted under `src/Redux/apiServices`.
   - Endpoint definitions are stored as JSON files in `src/Redux/apiServices/APIs/`, grouped by domain: `auth`, `expense`, and `user`.
   - `buildURL.ts` and `calAPPI.ts` appear to be the request construction/execution utilities.
   - This creates a clear separation between **feature actions** and **low-level HTTP details**.

9. **Data flow across the app**
   - Typical flow is:
     - user interacts with a page or custom form
     - feature component dispatches a Redux action
     - action calls the API service layer
     - reducer stores the result in domain state
     - page/component rerenders from Redux state
   - Lists such as users and expenses likely use the table components and pagination/filter helpers to render server-backed collections.

10. **Dashboard and list screens**
   - The **Home** area contains summary widgets like `TotalExpense` and `TotalExpenseForThisYear`.
   - The **Users** and **Expenses** areas have paired “create” and “see/list” flows, with dedicated table components for list views.
   - Expense editing is a separate component boundary (`EditExepense`), indicating item detail/update is treated as a distinct interaction path.

11. **Shared layout and navigation**
   - `src/Layouts/Sidebar` provides navigation structure for authenticated sections.
   - `src/Components/Header` and `src/Components/Profile/HeaderProfile` suggest a top bar/header region with profile/account affordances.
   - Together these form the authenticated shell around the feature pages.

12. **Styling and asset strategy**
   - Styling is mostly local-scoped via `styles.module.css` files, suggesting component-level CSS Modules are the primary styling boundary.
   - Global styles are in `src/index.css` and `src/App.css`.
   - Static files and PWA shell assets live in `public/`, including `manifest.json` and `index.html`.

13. **Types and validation concerns**
   - Type definitions are centralized in `src/Types` and feature-level `interfaces.ts` files.
   - `src/ErrorHandlers/ValidationError.ts` indicates validation failures are modeled explicitly rather than handled ad hoc.
   - This repository is strongly typed at the component and data-contract level, which is important for diagramming the boundaries between form inputs, API payloads, and Redux state.

14. **How to think about the architecture diagram**
   - Draw it as a **frontend SPA** with:
     - a routing/authentication layer
     - a layout shell
     - feature pages for auth/users/expenses/home
     - a shared reusable component library
     - a Redux state layer
     - an API service layer backed by endpoint definitions
     - cookie/token utilities for auth persistence
   - The main cross-cutting paths are **authentication**, **domain CRUD flows**, and **dashboard aggregation**.

Main entry points: [`src/Routes.tsx`](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Routes.tsx) (Routes), [`src/RoutesProtection/index.tsx`](https://github.com/saad036/house-build-expense-frontend/blob/main/src/RoutesProtection/index.tsx) (Route guard), [`src/Components/Expenses/ExpensePageComponent.tsx`](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Expenses/ExpensePageComponent.tsx) (Expenses module), [`src/Components/Custom/Form/index.tsx`](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Custom/Form/index.tsx) (Form system)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap & Routing"]
  node_src_index_tsx["App bootstrap<br/>entrypoint<br/>[index.tsx]"]
  node_src_app_tsx["App root<br/>spa root<br/>[App.tsx]"]
  node_src_routes_tsx["Routes<br/>route registry<br/>[Routes.tsx]"]
  node_src_routes_protection{{"Route guard<br/>auth gate<br/>[index.tsx]"}}
end

subgraph group_shell["Shell & Navigation"]
  node_src_layouts_index["Layout shell<br/>app shell<br/>[index.tsx]"]
  node_src_layouts_sidebar["Sidebar nav<br/>navigation<br/>[index.tsx]"]
  node_src_components_header["Header<br/>top bar<br/>[index.tsx]"]
  node_src_components_profile_header["Profile header<br/>account ui<br/>[index.tsx]"]
end

subgraph group_features["Feature Areas"]
  node_src_pages_auth_login["Login<br/>auth page<br/>[index.tsx]"]
  node_src_pages_home["Home page<br/>dashboard page<br/>[index.tsx]"]
  node_src_components_home["Dashboard<br/>summary widgets"]
  node_src_pages_users["Users page<br/>[index.tsx]"]
  node_src_components_users["Users module<br/>users feature"]
  node_src_pages_expenses["Expenses page<br/>[index.tsx]"]
  node_src_components_expenses["Expenses module<br/>expenses feature"]
end

subgraph group_ui["Shared UI"]
  node_src_custom_form["Form system<br/>form primitives<br/>[index.tsx]"]
  node_src_custom_table["Table system<br/>list primitives<br/>[index.tsx]"]
  node_src_custom_modal["Modal / popover<br/>overlay ui<br/>[index.tsx]"]
end

subgraph group_state["State & APIs"]
  node_src_redux_store[("Redux store<br/>state container<br/>[store.ts]")]
  node_src_redux_actions["Actions<br/>[authAction.ts]"]
  node_src_redux_reducers["Reducers<br/>[index.ts]"]
  node_src_redux_api["API services<br/>http layer<br/>[calAPPI.ts]"]
end

subgraph group_infra["Auth & Types"]
  node_src_util_cookies["Cookies<br/>token storage<br/>[Cookies.ts]"]
  node_src_util_user_token["User token<br/>auth util<br/>[UserToken.ts]"]
  node_src_error_validation["Validation error<br/>error model<br/>[ValidationError.ts]"]
  node_src_types["Shared types<br/>contracts<br/>[index.ts]"]
end

node_src_index_tsx -->|"boots"| node_src_app_tsx
node_src_app_tsx -->|"uses"| node_src_routes_tsx
node_src_routes_tsx -->|"guards"| node_src_routes_protection
node_src_routes_tsx -->|"routes to"| node_src_pages_auth_login
node_src_routes_tsx -->|"routes to"| node_src_pages_home
node_src_routes_tsx -->|"routes to"| node_src_pages_users
node_src_routes_tsx -->|"routes to"| node_src_pages_expenses
node_src_routes_protection -->|"wraps"| node_src_layouts_index
node_src_layouts_index -->|"includes"| node_src_layouts_sidebar
node_src_layouts_index -->|"includes"| node_src_components_header
node_src_components_header -->|"includes"| node_src_components_profile_header
node_src_pages_home -->|"composes"| node_src_components_home
node_src_pages_users -->|"composes"| node_src_components_users
node_src_pages_expenses -->|"composes"| node_src_components_expenses
node_src_pages_auth_login -->|"uses"| node_src_custom_form
node_src_components_users -->|"uses"| node_src_custom_form
node_src_components_users -->|"uses"| node_src_custom_table
node_src_components_expenses -->|"uses"| node_src_custom_form
node_src_components_expenses -->|"uses"| node_src_custom_table
node_src_components_expenses -->|"uses"| node_src_custom_modal
node_src_redux_store -->|"combines"| node_src_redux_reducers
node_src_redux_actions -->|"calls"| node_src_redux_api
node_src_redux_actions -->|"updates"| node_src_redux_reducers
node_src_redux_api -->|"uses"| node_src_types
node_src_routes_protection -->|"checks"| node_src_util_cookies
node_src_routes_protection -->|"checks"| node_src_util_user_token
node_src_custom_form -->|"reports"| node_src_error_validation
node_src_redux_actions -->|"types with"| node_src_types
node_src_redux_reducers -->|"types with"| node_src_types

click node_src_index_tsx "https://github.com/saad036/house-build-expense-frontend/blob/main/src/index.tsx"
click node_src_app_tsx "https://github.com/saad036/house-build-expense-frontend/blob/main/src/App.tsx"
click node_src_routes_tsx "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Routes.tsx"
click node_src_routes_protection "https://github.com/saad036/house-build-expense-frontend/blob/main/src/RoutesProtection/index.tsx"
click node_src_layouts_index "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Layouts/index.tsx"
click node_src_layouts_sidebar "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Layouts/Sidebar/index.tsx"
click node_src_components_header "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Header/index.tsx"
click node_src_components_profile_header "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Profile/HeaderProfile/index.tsx"
click node_src_pages_auth_login "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Pages/Auth/Login/index.tsx"
click node_src_pages_home "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Pages/Home/index.tsx"
click node_src_components_home "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Home/HomePageComponent.tsx"
click node_src_pages_users "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Pages/Users/index.tsx"
click node_src_components_users "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Users/UsersPageComponent.tsx"
click node_src_pages_expenses "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Pages/Expenses/index.tsx"
click node_src_components_expenses "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Expenses/ExpensePageComponent.tsx"
click node_src_custom_form "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Custom/Form/index.tsx"
click node_src_custom_table "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Custom/CustomTable/index.tsx"
click node_src_custom_modal "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Custom/CustomModal/index.tsx"
click node_src_redux_store "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Redux/store.ts"
click node_src_redux_actions "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Redux/actions/authAction.ts"
click node_src_redux_reducers "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Redux/reducers/index.ts"
click node_src_redux_api "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Redux/apiServices/calAPPI.ts"
click node_src_util_cookies "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Utilities/Cookies.ts"
click node_src_util_user_token "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Utilities/Users/UserToken.ts"
click node_src_error_validation "https://github.com/saad036/house-build-expense-frontend/blob/main/src/ErrorHandlers/ValidationError.ts"
click node_src_types "https://github.com/saad036/house-build-expense-frontend/blob/main/src/Types/index.ts"

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_src_index_tsx,node_src_app_tsx,node_src_routes_tsx,node_src_routes_protection toneBlue
class node_src_layouts_index,node_src_layouts_sidebar,node_src_components_header,node_src_components_profile_header toneAmber
class node_src_pages_auth_login,node_src_pages_home,node_src_components_home,node_src_pages_users,node_src_components_users,node_src_pages_expenses,node_src_components_expenses toneMint
class node_src_custom_form,node_src_custom_table,node_src_custom_modal toneRose
class node_src_redux_store,node_src_redux_actions,node_src_redux_reducers,node_src_redux_api toneIndigo
class node_src_util_cookies,node_src_util_user_token,node_src_error_validation,node_src_types toneTeal
```

## Components

### Bootstrap & Routing

Application entry, route registry, and protection boundary.

- [App bootstrap](https://github.com/saad036/house-build-expense-frontend/blob/main/src/index.tsx): entrypoint · Mounts the React app and initializes global providers. · `src/index.tsx`
- [App root](https://github.com/saad036/house-build-expense-frontend/blob/main/src/App.tsx): spa root · Top-level application composition boundary. · `src/App.tsx`
- [Routes](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Routes.tsx): route registry · Main client-side route map. · `src/Routes.tsx`
- [Route guard](https://github.com/saad036/house-build-expense-frontend/blob/main/src/RoutesProtection/index.tsx): auth gate · Protects authenticated sections and enforces access checks. · `src/RoutesProtection/index.tsx`

### Shell & Navigation

Authenticated layout and navigation structure.

- [Layout shell](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Layouts/index.tsx): app shell · Authenticated page frame and shared layout composition. · `src/Layouts/index.tsx`
- [Sidebar nav](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Layouts/Sidebar/index.tsx): navigation · Sidebar-based navigation for protected areas. · `src/Layouts/Sidebar/index.tsx`
- [Header](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Header/index.tsx): top bar · Shared header region for the authenticated shell. · `src/Components/Header/index.tsx`
- [Profile header](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Profile/HeaderProfile/index.tsx): account ui · Profile/account affordances in the top bar. · `src/Components/Profile/HeaderProfile/index.tsx`

### Feature Areas

Route-level pages and their major domain components.

- [Login](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Pages/Auth/Login/index.tsx): auth page · Authentication page and login flow. · `src/Pages/Auth/Login/index.tsx`
- [Home page](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Pages/Home/index.tsx): dashboard page · Route for the expense summary dashboard. · `src/Pages/Home/index.tsx`
- [Dashboard](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Home/HomePageComponent.tsx): summary widgets · Aggregates high-level expense metrics. · `src/Components/Home/HomePageComponent.tsx`
- [Users page](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Pages/Users/index.tsx): users page · Route-level users area for create and list flows. · `src/Pages/Users/index.tsx`
- [Users module](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Users/UsersPageComponent.tsx): users feature · Create/list user screens and table rendering. · `src/Components/Users/UsersPageComponent.tsx`
- [Expenses page](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Pages/Expenses/index.tsx): expenses page · Route-level expenses area for create, list, and edit flows. · `src/Pages/Expenses/index.tsx`
- [Expenses module](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Expenses/ExpensePageComponent.tsx): expenses feature · Create, edit, and list expense screens. · `src/Components/Expenses/ExpensePageComponent.tsx`

### Shared UI

Reusable presentation and form primitives.

- [Form system](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Custom/Form/index.tsx): form primitives · Shared form state and field wrappers used across features. · `src/Components/Custom/Form/index.tsx`
- [Table system](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Custom/CustomTable/index.tsx): list primitives · Shared table and filtering components for list screens. · `src/Components/Custom/CustomTable/index.tsx`
- [Modal / popover](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Components/Custom/CustomModal/index.tsx): overlay ui · Reusable overlays for confirmations and dialogs. · `src/Components/Custom/CustomModal/index.tsx`

### State & APIs

Redux state management and API integration.

- [Redux store](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Redux/store.ts): state container · Centralized application store setup. · `src/Redux/store.ts`
- [Actions](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Redux/actions/authAction.ts): domain actions · Domain action creators for auth, users, expenses, and general UI. · `src/Redux/actions/authAction.ts`
- [Reducers](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Redux/reducers/index.ts): domain reducers · Combined domain reducers for the application state model. · `src/Redux/reducers/index.ts`
- [API services](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Redux/apiServices/calAPPI.ts): http layer · Endpoint definitions and request construction helpers. · `src/Redux/apiServices/calAPPI.ts`

### Auth & Types

Persistence, validation, and shared type definitions.

- [Cookies](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Utilities/Cookies.ts): token storage · Cookie-based persistence for client auth state. · `src/Utilities/Cookies.ts`
- [User token](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Utilities/Users/UserToken.ts): auth util · Helpers for token handling and auth persistence. · `src/Utilities/Users/UserToken.ts`
- [Validation error](https://github.com/saad036/house-build-expense-frontend/blob/main/src/ErrorHandlers/ValidationError.ts): error model · Typed validation failure representation. · `src/ErrorHandlers/ValidationError.ts`
- [Shared types](https://github.com/saad036/house-build-expense-frontend/blob/main/src/Types/index.ts): contracts · Common type definitions for users, expenses, icons, and general contracts. · `src/Types/index.ts`

## Connections

- App bootstrap → App root: boots · Entry point renders the app root.
- App root → Routes: uses · App delegates navigation to the route registry.
- Routes → Route guard: guards · Protected areas pass through the access boundary.
- Routes → Login: routes to · Public auth route.
- Routes → Home page: routes to · Home dashboard route.
- Routes → Users page: routes to · Users route.
- Routes → Expenses page: routes to · Expenses route.
- Route guard → Layout shell: wraps · Protected routes render inside the authenticated shell.
- Layout shell → Sidebar nav: includes · Layout shell includes sidebar navigation.
- Layout shell → Header: includes · Layout shell includes top header.
- Header → Profile header: includes · Header exposes profile/account controls.
- Home page → Dashboard: composes · Home page is built from dashboard widgets.
- Users page → Users module: composes · Users page delegates to users feature module.
- Expenses page → Expenses module: composes · Expenses page delegates to expenses feature module.
- Login → Form system: uses · Login screen uses shared form primitives.
- Users module → Form system: uses · Users create flow uses shared form system.
- Users module → Table system: uses · Users list flow uses shared table system.
- Expenses module → Form system: uses · Expense create/edit flows use shared forms.
- Expenses module → Table system: uses · Expense list flow uses shared table system.
- Expenses module → Modal / popover: uses · Expense interactions use overlays for confirmations.
- Redux store → Reducers: combines · Store is built from the domain reducers.
- Actions → API services: calls · Actions delegate network work to API services.
- Actions → Reducers: updates · Actions feed state changes into reducers.
- API services → Shared types: uses · API contracts depend on shared types.
- Route guard → Cookies: checks · Auth gate reads persisted credentials.
- Route guard → User token: checks · Auth gate uses token helpers.
- Form system → Validation error: reports · Form subsystem surfaces validation failures.
- Actions → Shared types: types with · Domain actions share common contracts.
- Reducers → Shared types: types with · Reducers are shaped by shared contracts.