adding documentation
This commit is contained in:
@@ -1 +1,188 @@
|
||||
### GUI
|
||||
# Manager Employees GUI
|
||||
|
||||
> **This repository is the GUI frontend for Assignment 4: Implementing Control Structures.** It provides the visual interface to call and display results from the two backend implementations — Rust and Python — which contain the core scheduling logic.
|
||||
|
||||
**Author:** Carlos Gutierrez
|
||||
**Email:** cgutierrez44833@ucumberlands.edu
|
||||
**Course:** University of the Cumberlands — Semester 4, Week 4 — Assignment 4
|
||||
|
||||
## Repositories
|
||||
|
||||
| Project | Description | URL |
|
||||
| ----------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| **This GUI (Frontend)** | React + Vite dashboard that consumes the backends via `src/api/apiClient.ts:1` | https://git.cargdev.io/CarGDev/manager_employees_gui |
|
||||
| **Rust Backend** | Scheduling API in Rust (`http://localhost:5005` `src/api/backendConfig.ts:7`) | https://git.cargdev.io/CarGDev/manager_employees_rust |
|
||||
| **Python Backend** | Scheduling API in Python (`http://localhost:5006` `src/api/backendConfig.ts:13`) | https://git.cargdev.io/CarGDev/manager_employees_python |
|
||||
|
||||
Switch the active backend at runtime using the **Backend preference** selector in the sidebar (`src/layouts/AppLayout.tsx:43-56` -> `src/api/backendConfig.ts:20` `getBackendOption()`). All data fetching (`src/api/usersApi.ts:11`, `src/api/companiesApi.ts`, `src/api/scheduleApi.ts`, `src/api/endpoints.ts:1`) is routed through the selected base URL.
|
||||
|
||||
```
|
||||
[ GUI :3000 ] -- apiClient --> [ Rust :5005 / swagger-ui ]
|
||||
\--> [ Python :5006 / swagger-ui ]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## About Assignment 4: Implementing Control Structures
|
||||
|
||||
### My Story
|
||||
|
||||
For Assignment 4 I needed to demonstrate mastery of control structures — conditionals, loops, and branching — across different programming paradigms without logical errors. I chose a contrast of **Rust and Python** for the core scheduling engine (see repos above) because they represent distinctly different paradigms (systems/compiled vs. scripting/interpreted) as required by the assignment. The scheduling requirements are intentionally control-flow heavy (nested loops over 7 days x 3 shifts, conditionals for max 5 days/week, branching for conflict resolution), which made them ideal for comparing syntax and flow between languages.
|
||||
|
||||
To complete the **bonus GUI requirement**, I built this React/TypeScript frontend. While the backends enforce the algorithmic rules, this GUI provides the human interface for input (employee names and `WorkTime` preferences `src/types/users.ts:1` — `morning`|`afternoon`|`evening`) and output (weekly schedule calendar `src/pages/SchedulePage.tsx:36`). The shared type system (`src/types/schedule.ts:1`, `src/types/companies.ts:1`) and dual-backend toggle let me demonstrate the same control-structure logic running under two different implementations from a single UI.
|
||||
|
||||
### 1. Overview
|
||||
|
||||
You will implement, without logical errors, various control structures such as conditionals, loops, and branching, in multiple programming languages. This assignment will demonstrate your mastery of syntax and control flow in different paradigms.
|
||||
|
||||
### 2. Application Prompt
|
||||
|
||||
You are tasked with developing a small application for managing employee schedules at a company. The company operates 7 days a week and allows employees to choose shifts in the morning, afternoon, or evening. The application should manage and output the following:
|
||||
|
||||
1. **Input and Storage:** The application should collect employee names and their preferred shifts (morning, afternoon, or evening) for each day of the week. Store this information in an appropriate data structure.
|
||||
2. **Scheduling Logic:** Assign shifts for employees. Ensure that:
|
||||
- No employee works more than one shift per day.
|
||||
- An employee can work a maximum of 5 days per week.
|
||||
- The company must have at least 2 employees per shift per day. If fewer than 2 employees are available for a shift, randomly assign additional employees who have not worked 5 days yet.
|
||||
3. **Shift Conflicts:** Implement logic to detect and resolve conflicts where an employee's preferred shift is full for a given day. If a conflict occurs, assign the employee to another available shift on the same or next day.
|
||||
4. **Output:** After scheduling the shifts, the application should output the final schedule for the week in a readable format, indicating which employee is assigned to each shift on each day.
|
||||
5. **Bonus (optional):** Allow employees to indicate shift preferences with a priority ranking (e.g., morning is their first preference, evening is their second). Implement logic to accommodate these preferences as much as possible, while still ensuring company shift requirements are met. In addition to the core requirements of implementing control structures in multiple languages, students may choose to implement a Graphical User Interface (GUI) for both the input (employee names and shift preferences) and the output (final employee schedule) in one of the languages.
|
||||
|
||||
### 3. Programming Language Suggestions
|
||||
|
||||
You are free to choose any two languages, but the languages must be different enough that there's a distinct contrast. For example, do not pick C++ and C#. Suggested languages:
|
||||
|
||||
- Python
|
||||
- Java
|
||||
- C++
|
||||
- JavaScript
|
||||
- Go
|
||||
- Rust
|
||||
|
||||
**My choice:** Rust + Python (backends) + TypeScript/React (this GUI) — a clear paradigm contrast.
|
||||
|
||||
---
|
||||
|
||||
## What This GUI Does
|
||||
|
||||
This frontend **does not re-implement** the scheduling algorithm; it visualizes and drives it:
|
||||
|
||||
- **Dashboard** `src/pages/HomePage.tsx:16` — Total users, working today (`enter_time && !out_time`), companies.
|
||||
- **Users** `src/pages/UsersPage.tsx:57` — Table with company, preference (`WorkTime`), status (`off-duty`|`working`|`worked` `src/pages/UsersPage.tsx:22`), check-in/out times, days worked. Modals: Add user, update preference (`PUT /employees/:id/preference` `src/api/endpoints.ts:11`), clock-in/out (`src/api/scheduleApi.ts`).
|
||||
- **Companies** `src/pages/CompaniesPage.tsx:24` — Grid of companies + assigned employee names (`GET /companies/:name/employees/names` `src/api/endpoints.ts:7`), create company, assign employee, delete.
|
||||
- **Schedule** `src/pages/SchedulePage.tsx:36` — Weekly calendar Sunday–Saturday (`weekDays` `src/pages/SchedulePage.tsx:14`), groups `Schedule` (`src/types/schedule.ts:3`) by `day_of_week`, displays `enter_time`/`out_time`.
|
||||
- **Routing** — Custom `usePathname` hook `src/hooks/usePathname.ts:1` + `App.tsx:12-27` (`/`, `/users`, `/companies`, `/schedule`) inside `AppLayout` `src/layouts/AppLayout.tsx:17`.
|
||||
- **Priority Bonus** — `preference` + `WeeklyPreferenceRequest` (`src/types/users.ts:32`) with `first`/`second`/`third` `WorkTime` ranking supported via `updateUserWeeklyPreferences` `src/api/usersApi.ts:38`.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Layer | Tech | Version |
|
||||
| ----------- | ------------------------------------------ | --------------------------- |
|
||||
| UI | React + React DOM | `19.3.0` `package.json:10` |
|
||||
| Build | Vite + @vitejs/plugin-react | `7.0.0` `package.json:52` |
|
||||
| Language | TypeScript | `6.0.0` `package.json:50` |
|
||||
| Routing | react-router | `8.4.0` `package.json:12` |
|
||||
| State | Zustand | `5.0.15` `package.json:14` |
|
||||
| Styles | Sass | `1.104.1` `package.json:13` |
|
||||
| Lint/Format | ESLint 10 + Prettier 3 + typescript-eslint | `package.json:39-51` |
|
||||
| Testing | @testing-library/react, jest-dom | `package.json:6-9` |
|
||||
|
||||
Path aliases `tsconfig.json:16-23` / `vite.config.ts:6-14`: `@api`, `@components`, `@hooks`, `@layouts`, `@pages`, `@/types`.
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js >= 18, `pnpm` (or `npm`/`yarn`)
|
||||
- Rust backend running on `http://localhost:5005` and/or Python backend on `http://localhost:5006` (see their repos + Swagger `src/api/backendConfig.ts:8,14` at `/swagger-ui/#/`)
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# clone this GUI
|
||||
git clone https://git.cargdev.io/CarGDev/manager_employees_gui
|
||||
cd manager_employees_gui
|
||||
|
||||
# install deps
|
||||
pnpm install
|
||||
# or npm install / yarn
|
||||
|
||||
# start dev server (Vite port 3000 per vite.config.ts:17)
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
Open `http://localhost:3000`.
|
||||
|
||||
### Available Scripts
|
||||
|
||||
| Script | Command `package.json:17-24` | Description |
|
||||
| -------------- | ---------------------------- | ---------------------------------------- |
|
||||
| `dev` | `vite` | Start dev server |
|
||||
| `build` | `tsc -b && vite build` | Type-check + production build to `dist/` |
|
||||
| `preview` | `vite preview` | Preview production build |
|
||||
| `lint` | `eslint .` | Lint |
|
||||
| `lint:fix` | `eslint . --fix` | Lint + auto-fix |
|
||||
| `format` | `prettier . --write` | Format |
|
||||
| `format:check` | `prettier . --check` | Check formatting |
|
||||
|
||||
## Backend Configuration
|
||||
|
||||
Defined in `src/api/backendConfig.ts:3-24`:
|
||||
|
||||
| Label | Value `BackendPreference` `src/types/backend.ts:1` | baseUrl | Swagger |
|
||||
| ------ | -------------------------------------------------- | ----------------------- | ------------------------------------- |
|
||||
| Rust | `rust` (default `defaultBackendPreference`) | `http://localhost:5005` | `http://localhost:5005/swagger-ui/#/` |
|
||||
| Python | `python` | `http://localhost:5006` | `http://localhost:5006/swagger-ui/#/` |
|
||||
|
||||
Change via UI select or programmatically `getBackendOption(preference)`.
|
||||
|
||||
## API Endpoints
|
||||
|
||||
Centralized in `src/api/endpoints.ts:1`:
|
||||
|
||||
- `GET /health`, `GET/POST /companies`, `DELETE /companies/:id`, `POST /companies/:companyId/employees/:employeeId`, `GET /companies/:name/employees/names`
|
||||
- `GET/POST /employees`, `GET /employees/:id`, `PUT /employees/:id/preference`, `PUT /employees/:id/weekly-preferences`
|
||||
- `PUT /employees/:id/clock-in`, `PUT /employees/:id/clock-out`
|
||||
- `GET /schedules`, `GET /schedules/weekly`, `POST /schedules/weekly/generate`
|
||||
|
||||
Implemented via `apiRequest` `src/api/apiClient.ts:1`.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── api/ # apiClient, backendConfig, endpoints, users/companies/schedule/navigation APIs
|
||||
├── components/ # Modal.tsx, PageHeader.tsx
|
||||
├── layouts/ # AppLayout.tsx (+ .module.scss)
|
||||
├── pages/ # HomePage, UsersPage, CompaniesPage, SchedulePage
|
||||
├── hooks/ # usePathname.ts
|
||||
├── types/ # backend, users, companies, schedule, navigation
|
||||
├── constants/
|
||||
├── features/
|
||||
├── App.tsx # router + backendPreference state
|
||||
├── main.tsx # ReactDOM root + reportWebVitals
|
||||
└── index.css
|
||||
```
|
||||
|
||||
## Development Notes
|
||||
|
||||
- Strict TS (`tsconfig.json:9` `strict: true`), bundler resolution.
|
||||
- ESLint + `eslint-config-prettier` for no conflicts, `prettier` for formatting.
|
||||
- Run `pnpm lint:fix && pnpm format` before committing.
|
||||
|
||||
## Build & Preview
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
pnpm preview
|
||||
```
|
||||
|
||||
Output in `dist/` (and `build/` legacy). Deploy as static site; ensure backends are reachable or proxy accordingly.
|
||||
|
||||
## License
|
||||
|
||||
See `LICENSE` — same as parent project.
|
||||
|
||||
---
|
||||
|
||||
_This GUI fulfills the bonus GUI requirement for Assignment 4 while delegating all control-structure-heavy scheduling logic to the Rust and Python backends linked above._
|
||||
|
||||
Reference in New Issue
Block a user