Skip to content

Commit 6f6ef79

Browse files
conorheffronconorheffron
committed
Update architecture.md & README.md
1 parent 8a5a5b2 commit 6f6ef79

2 files changed

Lines changed: 213 additions & 53 deletions

File tree

‎README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,16 @@
2626

2727
[Sonar Cloud Overall Code Summary](https://sonarcloud.io/summary/overall?id=conorheffron_booking-sys&branch=main)
2828

29+
---
30+
31+
## 🏛️ System Architecture & Design
32+
33+
For an in-depth breakdown of the system design, detailed UML/Mermaid diagrams, component blueprints, end-to-end data flows, and user experience (UX) state machines, see our dedicated guide:
34+
35+
👉 **[System Architecture Documentation (architecture.md)](./architecture.md)**
36+
37+
---
38+
2939
## Technologies
3040
- python3, django 6 admin/framework, django.test, React 18, TypeScipt, & MySQL Server / Sqlite2
3141

‎architecture.md‎

Lines changed: 203 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -4,59 +4,111 @@ This document provides a comprehensive technical blueprint of the **Booking Syst
44

55
---
66

7-
## 1. High-Level System Architecture
7+
## 1. High-Level System Architecture & Design
88

99
The Booking System is designed as a decoupled client-server architecture. It consists of a modern Single Page Application (SPA) frontend and a relational database-backed web API service, coordinated locally through a reverse proxy/dev-proxy configuration and deployed via Docker containers.
1010

11-
### Architectural Component Diagram
11+
### 1.1 Granular System Components Design
12+
13+
The diagram below details the concrete components, files, utility modules, and database structures that interact across boundaries, illustrating the inner layers of both the React frontend and the Django backend:
1214

1315
```mermaid
14-
graph TD
15-
%% Client Tier
16-
subgraph Client Tier: Single Page Application
17-
Browser[Web Browser]
18-
ReactApp[React 19 SPA / TypeScript]
19-
style ReactApp fill:#61dafb,stroke:#333,stroke-width:2px,color:#000
16+
graph TB
17+
%% Styling classes
18+
classDef frontend fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#01579b;
19+
classDef backend fill:#e8f5e9,stroke:#388e3c,stroke-width:2px,color:#1b5e20;
20+
classDef storage fill:#eceff1,stroke:#455a64,stroke-width:2px,color:#263238;
21+
classDef ext fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#e65100;
22+
23+
subgraph FE [Frontend System Design - React 19 SPA]
24+
direction TB
25+
subgraph FE_Pages [UI Screen Pages]
26+
BP[BookingPage.tsx<br/><i>Home Screen</i>]
27+
RP[ReservationsPage.tsx<br/><i>Admin/Public List</i>]
28+
ERP[EditReservationPage.tsx<br/><i>Secure Editor</i>]
29+
LP[LoginPage.tsx<br/><i>Authentication Gate</i>]
30+
LOP[LogoutPage.tsx<br/><i>Session Cleanup</i>]
31+
end
32+
33+
subgraph FE_Comp [Reusable Shared Components]
34+
NAV[Navbar.tsx<br/><i>Unified Navigation</i>]
35+
end
36+
37+
subgraph FE_Utils [Utilities & State Handlers]
38+
AUTH_HELP[auth.ts<br/><i>getAuthStatus, loginUser, logoutUser</i>]
39+
C_USER[currentUserCache.tsx<br/><i>sessionStorage caching</i>]
40+
C_VER[appVersionCache.tsx<br/><i>localStorage caching</i>]
41+
UTIL[Utils.tsx<br/><i>getCSRFToken, getSlots</i>]
42+
end
2043
end
2144
22-
%% Proxy/Gateway
23-
subgraph Proxy & Routing Tier
24-
ViteProxy[Vite Development Server Proxy]
25-
style ViteProxy fill:#646cff,stroke:#333,stroke-width:2px,color:#fff
45+
subgraph BE [Backend System Design - Django 5.1 & DRF]
46+
direction TB
47+
subgraph BE_Routing [Routing & API Gateways]
48+
B_URLS[booking-sys/urls.py<br/><i>Root Router</i>]
49+
H_URLS[hr/urls.py<br/><i>App Specific Router</i>]
50+
DRF_SPEC[drf-spectacular<br/><i>Swagger & OpenAPI Doc</i>]
51+
end
52+
53+
subgraph BE_Controller [Controllers, Wrappers & Forms]
54+
V_WRAP[views.py<br/><i>DRF @api_view Wrappers</i>]
55+
V_CLASS[views.py: Views Class<br/><i>API Core Method Handlers</i>]
56+
V_TEMPL[views.py: Views.edit_reservation<br/><i>Legacy SSR HTML View</i>]
57+
F_CLASS[forms.py<br/><i>EditReservationForm / ReservationForm</i>]
58+
end
59+
60+
subgraph BE_Biz [Business Logic Layer]
61+
T_UTILS[time_utils.py: TimeUtils<br/><i>TZ Manager & Slot generator</i>]
62+
end
63+
64+
subgraph BE_Models [ORM Data Layer]
65+
M_RES[models.py: Reservation<br/><i>Active Data Model</i>]
66+
end
2667
end
2768
28-
%% Application Tier
29-
subgraph Service Tier: Django Backend
30-
Django[Django 5.1 Web Application]
31-
DRF[Django REST Framework / API Layers]
32-
Spectacular[DRF Spectacular / OpenAPI Doc Generator]
33-
TimeUtils[TimeUtils / TZ Manager]
34-
style Django fill:#092e20,stroke:#333,stroke-width:2px,color:#fff
69+
subgraph DB [Storage Tier]
70+
SQLITE[(SQLite3 Database<br/><i>db.sqlite3</i>)]
3571
end
3672
37-
%% Database Tier
38-
subgraph Storage Tier
39-
SQLite[(SQLite3 Database)]
40-
style SQLite fill:#003b57,stroke:#333,stroke-width:2px,color:#fff
73+
subgraph EXT [External Services]
74+
METEO[Open-Meteo Weather API<br/><i>Direct REST Fetch</i>]
4175
end
4276
43-
%% External APIs
44-
subgraph External Services
45-
OpenMeteo[Open-Meteo Weather Forecast API]
46-
style OpenMeteo fill:#ff9900,stroke:#333,stroke-width:2px,color:#000
47-
end
77+
%% Apply Styles
78+
class BP,RP,ERP,LP,LOP FE_Pages;
79+
class NAV FE_Comp;
80+
class AUTH_HELP,C_USER,C_VER,UTIL FE_Utils;
81+
class B_URLS,H_URLS,DRF_SPEC BE_Routing;
82+
class V_WRAP,V_CLASS,V_TEMPL,F_CLASS BE_Controller;
83+
class T_UTILS BE_Biz;
84+
class M_RES BE_Models;
85+
class SQLITE DB;
86+
class METEO EXT;
4887
4988
%% Interactions
50-
Browser -->|Serves Assets / Interacts| ReactApp
51-
ReactApp -->|1. Weather Fetch: Direct HTTPS| OpenMeteo
52-
ReactApp -->|2. Local API Calls /api/*| ViteProxy
53-
ViteProxy -->|3. Proxy to Port 8000| DRF
54-
DRF -->|ORM Calls| SQLite
55-
Django -->|Configures| DRF
56-
Spectacular -->|Scans Views| DRF
89+
BP -->|Direct HTTPS GET| METEO
90+
FE_Pages --> NAV
91+
NAV --> C_USER
92+
NAV --> C_VER
93+
NAV --> AUTH_HELP
94+
95+
BP & ERP & RP -->|Imports| UTIL
96+
97+
%% Proxy Channel
98+
FE_Pages ====>|JSON API Requests<br/>via Vite DevProxy| B_URLS
99+
B_URLS --> H_URLS
100+
H_URLS --> V_WRAP
101+
V_WRAP --> V_CLASS
102+
V_CLASS --> T_UTILS
103+
V_CLASS --> M_RES
104+
105+
%% Server Side Rendered view connection
106+
V_TEMPL -.->|Imports/Validates| F_CLASS
107+
108+
M_RES -->|Django ORM Queries| SQLITE
57109
```
58110

59-
### ASCII High-Level Architecture representation
111+
### 1.2 Physical Infrastructure & Traffic Proxy
60112

61113
```text
62114
+------------------------------------------------------------+
@@ -96,11 +148,111 @@ graph TD
96148

97149
---
98150

99-
## 2. Backend Technical Overview
151+
## 2. UX Flow & State Transitions
152+
153+
The application presents a fluid, responsive user experience. It maps client-side interactions to secure screens, using route guards to intercept unauthenticated requests and gracefully managing input errors with real-time feedback.
154+
155+
### 2.1 UX Screen State Transition Diagram
156+
157+
The following state machine chart details how screens transition during standard operations, emphasizing route guarding and redirection context matching:
158+
159+
```mermaid
160+
stateDiagram-v2
161+
classDef guest fill:#e1f5fe,stroke:#0288d1,stroke-dasharray: 5 5;
162+
classDef auth fill:#e8f5e9,stroke:#388e3c;
163+
classDef err fill:#ffebee,stroke:#c62828;
164+
165+
[*] --> BookingPage_Guest : Init Browse (/)
166+
167+
state "BookingPage (Home Screen)" as BookingPage_Guest {
168+
[*] --> FetchWeather : Load Screen
169+
FetchWeather --> DisplayWeather : Success
170+
FetchWeather --> WeatherError : Fails (Silent Fallback)
171+
--
172+
[*] --> FetchTodayBookings : Load Screen
173+
FetchTodayBookings --> ShowBookingsList
174+
}
175+
176+
BookingPage_Guest --> LoginPage : Click "Login" on Navbar
177+
BookingPage_Guest --> ReservationsPage : Click "Bookings" on Navbar
178+
179+
state "LoginPage Screen (/login)" as LoginPage {
180+
[*] --> EnterCredentials
181+
EnterCredentials --> AuthenticateSession : Submit Form
182+
AuthenticateSession --> CreateCookie : Success [200 OK]
183+
AuthenticateSession --> DisplayAuthError : Invalid Credentials [41]
184+
}
185+
186+
DisplayAuthError --> EnterCredentials : Retry
187+
188+
state "ReservationsPage (/reservations)" as ReservationsPage {
189+
[*] --> LoadAllReservations
190+
LoadAllReservations --> ShowReservationsTable
191+
ShowReservationsTable --> TriggerDelete : Click "Delete" Button
192+
ShowReservationsTable --> TriggerClearAll : Click "Clear All" Button
193+
}
194+
195+
state "EditReservationPage (/reservations/edit/:id)" as EditReservationPage {
196+
[*] --> LoadReservationDetail : Fetch booking details
197+
LoadReservationDetail --> DisplayEditForm
198+
DisplayEditForm --> ValidateEditSubmit : Submit Edited Form
199+
}
200+
201+
%% Guard Checking
202+
ReservationsPage --> RequireAuthGuard : Click "Edit" Button on Row
203+
204+
state RequireAuthGuard <<choice>>
205+
RequireAuthGuard --> EditReservationPage : Authenticated [True]
206+
RequireAuthGuard --> LoginPage : Unauthenticated [False] <br/><i>(Saves "from" route in location.state)</i>
207+
208+
LoginPage --> RouteRecovery <<choice>> : Successful Authentication
209+
RouteRecovery --> EditReservationPage : Redirect to target route <br/><i>(e.g., /reservations/edit/:id)</i>
210+
RouteRecovery --> BookingPage_Guest : No target saved (Default to /)
211+
212+
%% Back paths
213+
EditReservationPage --> ReservationsPage : Submit Success [Redirects with 1.2s delay]
214+
EditReservationPage --> ReservationsPage : Click "Cancel"
215+
216+
%% Logout Operation
217+
ReservationsPage --> LogoutPage : Click "Logout" on Navbar
218+
LogoutPage --> BookingPage_Guest : Clears session caches & Redirects to Home
219+
220+
class BookingPage_Guest,ReservationsPage guest;
221+
class EditReservationPage,LoginPage,RouteRecovery auth;
222+
class DisplayAuthError,RequireAuthGuard err;
223+
```
224+
225+
### 2.2 Interactive UX Scenario Playbooks
226+
227+
#### Scenario A: The Guest Booking Workflow
228+
1. **Landing**: The user lands on `/` (`BookingPage`). The weather module fetches Dublin meteorological stats dynamically from Open-Meteo.
229+
2. **Date Picking**: Choosing a date triggers an async fetch to retrieve current bookings for that date.
230+
3. **Form Entry**: Fills in the name and picks a 30-minute interval from the dropdown selection list.
231+
4. **Submission**: Click **Reserve**.
232+
- **Case 1 (Invalid Input - Past Reservation)**: Backend rejects with `400 Bad Request`. An alert banner is shown with the message `Cannot make a reservation for a past date/time.`
233+
- **Case 2 (Invalid Input - Double Booking)**: Slot is occupied. Backend returns `400 Bad Request` with `Booking Failed: Already Reserved.`
234+
- **Case 3 (Valid Input)**: Backend creates the slot and responds with `201 Created`. The list of bookings for that date is refreshed, and a success banner is shown which automatically fades after 3 seconds.
235+
236+
#### Scenario B: The Secure Edit Redirect Journey (Route Guarding)
237+
1. **Browse**: User lands on `/reservations`, browsing the list of bookings.
238+
2. **Action**: User clicks the **Edit** link next to a specific reservation row.
239+
3. **Guard Check**: The `RequireAuth` higher-order component intercepts the route, executing a background query (`getAuthStatus()`) to check if the session is authenticated.
240+
4. **Redirect**:
241+
- The user is not logged in. `RequireAuth` redirects them to `/login` using:
242+
```typescript
243+
<Navigate to="/login" replace state={{ from: location }} />
244+
```
245+
5. **Login**: User inputs credentials. Upon validation, the page retrieves the state:
246+
- It redirects the user straight to the edit route saved in `state.from` (e.g., `/reservations/edit/12`).
247+
6. **Modification**: The user modifies the booking and clicks **Save**. A success message appears, and after 1.2 seconds they are redirected back to the `/reservations` page.
248+
249+
---
250+
251+
## 3. Backend Technical Overview
100252

101253
The backend is built on **Django 5.1** and structured around a main app called `hr`. It serves as a secure RESTful API provider using the **Django REST Framework (DRF)**. API contract specifications and Interactive API documentation are automatically managed via **drf-spectacular**.
102254

103-
### 2.1 Database Models & Relations
255+
### 3.1 Database Models & Relations
104256

105257
The application employs a streamlined relational schema centered around a single core entity representing reservations.
106258

@@ -122,7 +274,7 @@ erDiagram
122274
- `reservation_date`: A DateField representing the date of reservation.
123275
- `reservation_slot`: A TimeField representing the specific reservation hour (e.g., "14:30:00").
124276

125-
### 2.2 Timezone and Reservation Slot Business Logic
277+
### 3.2 Timezone and Reservation Slot Business Logic
126278

127279
Reservations are governed by precise timezone and scheduling boundaries implemented in `backend/hr/time_utils.py` and validated inside views.
128280

@@ -133,7 +285,7 @@ Reservations are governed by precise timezone and scheduling boundaries implemen
133285
- Eligible timeslots range from **09:00 AM to 07:00 PM** at **30-minute intervals** (i.e. `09:00 AM, 09:30 AM, ..., 06:30 PM, 07:00 PM`).
134286
- `TimeUtils.generate_time_slots` handles the logical matrix calculation to generate standard choice mappings.
135287

136-
### 2.3 Security, Sessions, and Session Synchronization
288+
### 3.3 Security, Sessions, and Session Synchronization
137289

138290
Security is enforced at multiple layers:
139291

@@ -146,7 +298,7 @@ Security is enforced at multiple layers:
146298

147299
---
148300

149-
## 3. API Endpoint Registry
301+
## 4. API Endpoint Registry
150302

151303
All backend services are exposed via standardized JSON endpoints mapped in `backend/hr/urls.py` and documented in Swagger.
152304

@@ -167,11 +319,11 @@ All backend services are exposed via standardized JSON endpoints mapped in `back
167319

168320
---
169321

170-
## 4. Frontend Technical Overview
322+
## 5. Frontend Technical Overview
171323

172324
The client-side application is a single-page architecture built with **React 19** and **TypeScript 5**, configured with **Vite 8** for lightning-fast bundling, HMR, and proxy routing during development.
173325

174-
### 4.1 Routing & Navigation State
326+
### 5.1 Routing & Navigation State
175327

176328
Frontend URL routing is managed by `react-router-dom` (v7) inside `frontend/src/main.tsx`. Routes are defined as follows:
177329

@@ -193,9 +345,7 @@ Frontend URL routing is managed by `react-router-dom` (v7) inside `frontend/src/
193345
[EditReservationPage]
194346
```
195347

196-
- **`RequireAuth` Guard Component**: Intercepts requests to `/reservations/edit/:id`. It fires a background verification check using `getAuthStatus()`. If the user is unauthenticated, it redirects them to `/login` while passing the current path inside React Router's location state (`state: { from: location }`) to support automatic return redirection upon successful login.
197-
198-
### 4.2 Local Cache Strategies
348+
### 5.2 Local Cache Strategies
199349

200350
To minimize redundant server roundtrips and improve user experience, the frontend implements two caching utilities:
201351

@@ -206,7 +356,7 @@ To minimize redundant server roundtrips and improve user experience, the fronten
206356
- Caches the authenticated user's name returned by `/api/user/` in `sessionStorage`.
207357
- Prevents refetching username strings during component re-renders of the `Navbar` across pages, clearing immediately when the session is closed or when a user logs out.
208358

209-
### 4.3 Third-Party Weather API Integration
359+
### 5.3 Third-Party Weather API Integration
210360

211361
To help users select the best reservation times, the `BookingPage` displays a real-time **Dublin Weather Snapshot** by connecting to the public **Open-Meteo API**:
212362
- **Endpoint**: `https://api.open-meteo.com/v1/forecast?latitude=53.3498&longitude=-6.2603&current=temperature_2m,wind_speed_10m,weather_code&timezone=auto`
@@ -215,9 +365,9 @@ To help users select the best reservation times, the `BookingPage` displays a re
215365

216366
---
217367

218-
## 5. End-to-End System Data Flows
368+
## 6. End-to-End System Data Flows
219369

220-
### 5.1 Authentication and Session Setup Flow
370+
### 6.1 Authentication and Session Setup Flow
221371

222372
This sequence demonstrates how a user establishes an authenticated session to manage bookings.
223373

@@ -244,7 +394,7 @@ sequenceDiagram
244394
Frontend->>User: Redirect to index / previous page
245395
```
246396

247-
### 5.2 Creating a Booking Flow
397+
### 6.2 Creating a Booking Flow
248398

249399
This sequence demonstrates creating a reservation, detailing the validations performed.
250400

@@ -287,11 +437,11 @@ sequenceDiagram
287437

288438
---
289439

290-
## 6. Deployment & Development Architecture
440+
## 7. Deployment & Development Architecture
291441

292442
The development and containerization workflow uses a unified, deterministic environment.
293443

294-
### 6.1 Multi-Process Container Setup
444+
### 7.1 Multi-Process Container Setup
295445

296446
Local deployments are fully containerized using **Docker** and **Docker Compose**.
297447

@@ -307,7 +457,7 @@ Local deployments are fully containerized using **Docker** and **Docker Compose*
307457
3. Starts Vite dev server: `npm run dev -- --host` (Foreground).
308458
- Port `8000` (Django REST API) and Port `5173` (Vite) are both exposed through Docker Compose to host interfaces.
309459

310-
### 6.2 Testing Framework
460+
### 7.2 Testing Framework
311461

312462
The application ensures stability through parallel testing pipelines:
313463

0 commit comments

Comments
 (0)