# fahmudul/apartment-construction-expense-management-system architecture

> Architecture diagram of the GitHub repository fahmudul/apartment-construction-expense-management-system, 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/fahmudul/apartment-construction-expense-management-system
- Repository: https://github.com/fahmudul/apartment-construction-expense-management-system

## Overview

1. This is a desktop CRUD application built with C# Windows Forms on .NET 10. The runtime boundary is entirely local on the user’s machine: UI forms call application services, which talk directly to SQL Server via `Microsoft.Data.SqlClient`.

2. The codebase is organized in a classic WinForms layering:
   - `Forms/` contains the screens and all UI workflows.
   - `Services/` contains business logic and database operations.
   - `Models/` contains simple data objects for `User`, `Category`, and `Expense`.
   - `Helpers/` contains cross-cutting utilities such as database connection setup and UI theming.
   - `Controls/` contains reusable UI components like the custom sidebar button.

3. Application startup is centered in `Program.cs`, which launches the WinForms shell and routes the user into the authentication flow. From there, the login/registration screens decide which main dashboard to open based on role and status.

4. Authentication and approval are a major subsystem. `AuthService` supports login, registration, and session-related decisions. New users register into a `Pending` status, then `PendingApprovalForm` communicates that they must wait for admin approval before login is allowed. This creates a clear boundary between self-service registration and admin-controlled access.

5. Role-based UI is split into admin and user experiences. Admin screens include `AdminDashboardForm`, `AdminUsersForm`, `AdminCategoriesForm`, and `AdminExpensesForm`. User screens include `UserDashboardForm`, `UserExpensesForm`, `AddExpenseForm`, and `UserDetailsForm`. The dashboards are separate, not just filtered views, which matters for diagramming the app’s navigation structure.

6. User management is handled by `UserService` and the admin user forms. The system supports approving, rejecting, blocking, and unblocking accounts, with actions depending on both role and current status. This makes user state a first-class domain concept rather than just a login flag.

7. Category management is isolated in `CategoryService` plus the admin category forms. Categories are stored as shared master data and are used as lookup values when creating expenses. The presence of `EditCategoryForm` indicates a dedicated edit workflow rather than inline editing.

8. Expense handling is the main transactional subsystem. `ExpenseService` manages create, read, and delete operations, and is used by both admin and user screens. Users can add and delete their own expenses through `AddExpenseForm` and `UserExpensesForm`, while admins can view all expenses in `AdminExpensesForm`.

9. The data model is straightforward and relational. `Users` is the identity and access table, `Categories` is the lookup/master table, and `Expenses` references both `Users` and `Categories`. The schema in `DatabaseSetup.sql` enforces the primary relationships: each expense belongs to exactly one user and one category.

10. `Helpers/DatabaseHelper.cs` is an important infrastructure boundary. It centralizes database connection creation and reads environment-specific settings from `.env`, allowing local development settings to differ from other environments. This is paired with `DotNetEnv` support mentioned in the README, so configuration is externalized rather than hardcoded.

11. The UI layer uses Windows Forms designer/code-behind pairs throughout. Each `.Designer.cs` file defines layout, while the corresponding `.cs` file holds event handling and form logic. This separation is important for understanding where presentation ends and behavior begins.

12. `Helpers/UITheme.cs` and `Controls/SidebarButton.cs` indicate a shared visual system. `UITheme` standardizes colors, fonts, and likely control styling across forms, while the sidebar button provides reusable navigation behavior in the admin/user shell.

13. The repository also includes SQL scripts (`DatabaseSetup.sql` and `Helpers/SQLQuery1.sql`) and screenshots under `docs/screenshots`, which support setup and documentation but are not part of runtime behavior. For an architecture diagram, the key runtime path is: WinForms UI → service layer → SQL Server database, with shared helpers and models in between.

Main entry points: [`Services/ExpenseService.cs`](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Services/ExpenseService.cs) (ExpenseService), [`Services/AuthService.cs`](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Services/AuthService.cs) (AuthService), [`Forms/AdminDashboardForm.cs`](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/AdminDashboardForm.cs) (Admin Dashboard), [`Forms/UserDashboardForm.cs`](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/UserDashboardForm.cs) (User Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup"]
  node_program["Program<br/>winforms entry<br/>[Program.cs]"]
end

subgraph group_ui_auth["Authentication UI"]
  node_login_form["Login<br/>auth form<br/>[LoginForm.cs]"]
  node_register_form["Register<br/>auth form<br/>[RegisterForm.cs]"]
  node_pending_form["Pending<br/>status form"]
end

subgraph group_ui_admin["Admin UI"]
  node_admin_dashboard["Admin Dashboard<br/>admin shell"]
  node_admin_users["Users<br/>admin user mgmt<br/>[AdminUsersForm.cs]"]
  node_admin_categories["Categories<br/>admin master data"]
  node_admin_expenses["Expenses<br/>admin ledger view"]
end

subgraph group_ui_user["User UI"]
  node_user_dashboard["User Dashboard<br/>user shell"]
  node_user_expenses["My Expenses<br/>user ledger"]
  node_add_expense["Add Expense<br/>expense entry form<br/>[AddExpenseForm.cs]"]
  node_user_details["Profile<br/>user details<br/>[UserDetailsForm.cs]"]
end

subgraph group_services["Services"]
  node_auth_service["AuthService<br/>auth logic<br/>[AuthService.cs]"]
  node_user_service["UserService<br/>user admin logic<br/>[UserService.cs]"]
  node_category_service["CategoryService<br/>master data logic<br/>[CategoryService.cs]"]
  node_expense_service["ExpenseService<br/>transaction logic<br/>[ExpenseService.cs]"]
end

subgraph group_domain["Domain Models"]
  node_user_model["User<br/>model<br/>[User.cs]"]
  node_category_model["Category<br/>model<br/>[Category.cs]"]
  node_expense_model["Expense<br/>model<br/>[Expense.cs]"]
end

subgraph group_infra["Infrastructure"]
  node_db_helper["DatabaseHelper<br/>db connection helper<br/>[DatabaseHelper.cs]"]
  node_ui_theme["UITheme<br/>ui styling helper<br/>[UITheme.cs]"]
  node_sidebar_button["SidebarButton<br/>ui control<br/>[SidebarButton.cs]"]
  node_sql_server[("SQL Server<br/>database")]
end

node_program -->|"launches"| node_login_form
node_login_form -->|"authenticates via"| node_auth_service
node_register_form -->|"registers via"| node_auth_service
node_pending_form -.->|"returns to"| node_login_form
node_auth_service -->|"checks state"| node_user_service
node_auth_service -->|"opens"| node_admin_dashboard
node_auth_service -->|"opens"| node_user_dashboard
node_admin_dashboard -->|"navigates"| node_admin_users
node_admin_dashboard -->|"navigates"| node_admin_categories
node_admin_dashboard -->|"navigates"| node_admin_expenses
node_user_dashboard -->|"navigates"| node_user_expenses
node_user_dashboard -->|"navigates"| node_add_expense
node_user_dashboard -->|"navigates"| node_user_details
node_admin_users -->|"manages"| node_user_service
node_admin_categories -->|"manages"| node_category_service
node_admin_expenses -->|"reads via"| node_expense_service
node_user_expenses -->|"reads/deletes via"| node_expense_service
node_add_expense -->|"creates via"| node_expense_service
node_expense_service -->|"uses"| node_user_model
node_expense_service -->|"uses"| node_category_model
node_expense_service -->|"maps"| node_expense_model
node_user_service -->|"maps"| node_user_model
node_category_service -->|"maps"| node_category_model
node_auth_service -->|"connects through"| node_db_helper
node_user_service -->|"connects through"| node_db_helper
node_category_service -->|"connects through"| node_db_helper
node_expense_service -->|"connects through"| node_db_helper
node_db_helper -->|"connects to"| node_sql_server
node_ui_theme -.->|"styles"| node_login_form
node_ui_theme -.->|"styles"| node_admin_dashboard
node_ui_theme -.->|"styles"| node_user_dashboard
node_sidebar_button -.->|"used by"| node_admin_dashboard
node_sidebar_button -.->|"used by"| node_user_dashboard

click node_program "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Program.cs"
click node_login_form "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/LoginForm.cs"
click node_register_form "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/RegisterForm.cs"
click node_pending_form "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/PendingApprovalForm.cs"
click node_auth_service "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Services/AuthService.cs"
click node_admin_dashboard "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/AdminDashboardForm.cs"
click node_admin_users "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/AdminUsersForm.cs"
click node_admin_categories "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/AdminCategoriesForm.cs"
click node_admin_expenses "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/AdminExpensesForm.cs"
click node_user_dashboard "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/UserDashboardForm.cs"
click node_user_expenses "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/UserExpensesForm.cs"
click node_add_expense "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/AddExpenseForm.cs"
click node_user_details "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/UserDetailsForm.cs"
click node_user_service "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Services/UserService.cs"
click node_category_service "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Services/CategoryService.cs"
click node_expense_service "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Services/ExpenseService.cs"
click node_user_model "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Models/User.cs"
click node_category_model "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Models/Category.cs"
click node_expense_model "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Models/Expense.cs"
click node_db_helper "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Helpers/DatabaseHelper.cs"
click node_ui_theme "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Helpers/UITheme.cs"
click node_sidebar_button "https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Controls/SidebarButton.cs"

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_program,node_db_helper,node_ui_theme,node_sidebar_button,node_sql_server toneBlue
class node_login_form,node_register_form,node_pending_form toneAmber
class node_admin_dashboard,node_admin_users,node_admin_categories,node_admin_expenses toneMint
class node_user_dashboard,node_user_expenses,node_add_expense,node_user_details toneRose
class node_auth_service,node_user_service,node_category_service,node_expense_service toneIndigo
class node_user_model,node_category_model,node_expense_model toneTeal
```

## Components

### Startup

App entry and launch flow

- [Program](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Program.cs): winforms entry · Application startup and shell launch · `Program.cs`

### Authentication UI

Login and registration boundary

- [Login](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/LoginForm.cs): auth form · User sign-in entry point · `Forms/LoginForm.cs`
- [Register](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/RegisterForm.cs): auth form · New account registration into pending status · `Forms/RegisterForm.cs`
- [Pending](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/PendingApprovalForm.cs): status form · Informs users they await approval · `Forms/PendingApprovalForm.cs`

### Admin UI

Role-based admin workflows

- [Admin Dashboard](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/AdminDashboardForm.cs): admin shell · Primary admin navigation and overview · `Forms/AdminDashboardForm.cs`
- [Users](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/AdminUsersForm.cs): admin user mgmt · Approve, reject, block, and unblock accounts · `Forms/AdminUsersForm.cs`
- [Categories](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/AdminCategoriesForm.cs): admin master data · Manage shared expense categories · `Forms/AdminCategoriesForm.cs`
- [Expenses](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/AdminExpensesForm.cs): admin ledger view · View all expenses across users · `Forms/AdminExpensesForm.cs`

### User UI

Role-based user workflows

- [User Dashboard](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/UserDashboardForm.cs): user shell · Primary user navigation and overview · `Forms/UserDashboardForm.cs`
- [My Expenses](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/UserExpensesForm.cs): user ledger · View and delete owned expenses · `Forms/UserExpensesForm.cs`
- [Add Expense](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/AddExpenseForm.cs): expense entry form · Create a new expense record · `Forms/AddExpenseForm.cs`
- [Profile](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Forms/UserDetailsForm.cs): user details · View personal account details · `Forms/UserDetailsForm.cs`

### Services

Business logic and persistence

- [AuthService](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Services/AuthService.cs): auth logic · Login, registration, and session decisions · `Services/AuthService.cs`
- [UserService](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Services/UserService.cs): user admin logic · Account state transitions and user management · `Services/UserService.cs`
- [CategoryService](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Services/CategoryService.cs): master data logic · Category lookup and maintenance · `Services/CategoryService.cs`
- [ExpenseService](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Services/ExpenseService.cs): transaction logic · Create, read, and delete expenses · `Services/ExpenseService.cs`

### Domain Models

Shared data objects

- [User](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Models/User.cs): model · Identity and status data · `Models/User.cs`
- [Category](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Models/Category.cs): model · Shared category lookup data · `Models/Category.cs`
- [Expense](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Models/Expense.cs): model · Expense transaction data · `Models/Expense.cs`

### Infrastructure

Database and shared UI utilities

- [DatabaseHelper](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Helpers/DatabaseHelper.cs): db connection helper · Centralized connection creation and .env-based config · `Helpers/DatabaseHelper.cs`
- [UITheme](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Helpers/UITheme.cs): ui styling helper · Shared colors, fonts, and control styling · `Helpers/UITheme.cs`
- [SidebarButton](https://github.com/fahmudul/apartment-construction-expense-management-system/blob/main/Controls/SidebarButton.cs): ui control · Reusable navigation button control · `Controls/SidebarButton.cs`
- **SQL Server**: database · Local relational datastore for users, categories, and expenses

## Connections

- Program → Login: launches · Startup opens the authentication flow
- Login → AuthService: authenticates via · Login screen delegates credentials to service layer
- Register → AuthService: registers via · Registration creates pending accounts
- Pending → Login: returns to · Users wait until approval allows login
- AuthService → UserService: checks state · Authentication depends on account status and role
- AuthService → Admin Dashboard: opens · Approved admin users enter admin shell
- AuthService → User Dashboard: opens · Approved standard users enter user shell
- Admin Dashboard → Users: navigates · Admin shell routes to user management
- Admin Dashboard → Categories: navigates · Admin shell routes to category management
- Admin Dashboard → Expenses: navigates · Admin shell routes to expense review
- User Dashboard → My Expenses: navigates · User shell routes to owned expenses
- User Dashboard → Add Expense: navigates · User shell routes to expense creation
- User Dashboard → Profile: navigates · User shell routes to profile details
- Users → UserService: manages · Approve, reject, block, and unblock accounts
- Categories → CategoryService: manages · Category workflows use service layer
- Expenses → ExpenseService: reads via · Admin views all expenses through service layer
- My Expenses → ExpenseService: reads/deletes via · Users load and delete their own expenses
- Add Expense → ExpenseService: creates via · Expense entry persists through service layer
- ExpenseService → User: uses · Expense operations reference user identity
- ExpenseService → Category: uses · Expense operations reference category lookup
- ExpenseService → Expense: maps · Expense service works with transaction entities
- UserService → User: maps · User service works with account entities
- CategoryService → Category: maps · Category service works with master data entities
- AuthService → DatabaseHelper: connects through · Authentication relies on centralized database access
- UserService → DatabaseHelper: connects through · User management uses shared connection setup
- CategoryService → DatabaseHelper: connects through · Category management uses shared connection setup
- ExpenseService → DatabaseHelper: connects through · Expense persistence uses shared connection setup
- DatabaseHelper → SQL Server: connects to · Centralized SQL Server connectivity boundary
- UITheme → Login: styles · Shared theming supports WinForms screens
- UITheme → Admin Dashboard: styles · Shared theming supports admin screens
- UITheme → User Dashboard: styles · Shared theming supports user screens
- SidebarButton → Admin Dashboard: used by · Reusable navigation control in shells
- SidebarButton → User Dashboard: used by · Reusable navigation control in shells