Skip to content

Commit d4afffa

Browse files
conorheffronconorheffron
committed
Update architecture.md & README.md
1 parent b5d7e54 commit d4afffa

2 files changed

Lines changed: 149 additions & 33 deletions

File tree

‎ARCHITECTURE.md‎

Lines changed: 140 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -12,15 +12,15 @@ The iRonoc portfolio platform is structured as a decoupled, multi-tier full-stac
1212
+---------------------------------------------------------------------------------------------------+
1313
| Client Web Browser |
1414
| - Renders UI elements (React 19, Material UI 7, Bootstrap 5) |
15-
| - Triggers Client-Side Routes, REST Calls, and real-time GraphQL Subscription streams |
15+
| - Triggers Client-Side Routes, REST Calls, and real-time GraphQL Subscription streams |
1616
+-------------------------------------------------+-------------------------------------------------+
1717
|
1818
| HTTP / HTTPS / WSS (WebSockets)
1919
v
2020
+---------------------------------------------------------------------------------------------------+
2121
| Gateway / Proxy Layer |
2222
| - Serves compiled, static frontend bundles (.js, .css, .html) from Tomcat /static mapping |
23-
| - Reverse-proxies API endpoints (/api/*) and GraphQL gateways (/graphql) to active servlet hooks |
23+
| - Reverse-proxies API endpoints (/api/*) and GraphQL gateways (/graphql) to active servlet hooks |
2424
+-------------------------------------------------+-------------------------------------------------+
2525
|
2626
v
@@ -59,44 +59,151 @@ The iRonoc portfolio platform is structured as a decoupled, multi-tier full-stac
5959

6060
---
6161

62-
## 2. Technical Sequence & Workflow Diagrams
62+
## 2. Technical Sequence & System Blueprint Diagrams
6363

6464
These diagrams can be visualized natively inside IntelliJ IDEA (using the diagram viewer plugin), GitHub, or standard markdown readers.
6565

66-
### 1. High-Level System Components & Services Flow
67-
This flowchart maps the primary components and structural dependencies from client interface to datastores and remote services.
66+
### 1. Granular System Design Blueprint (C4 Container-level Detail)
67+
This container blueprint details the precise boundaries, filter intercepts, servlet mappings, and multi-thread caching layers inside the Spring Boot container.
6868

6969
```mermaid
70-
flowchart TD
71-
subgraph Client [Client-Side Browser]
72-
A[React 19 Frontend SPA] -->|GraphQL Queries / Mutations / Subscriptions | B(Apollo Client)
73-
A -->|REST API Requests| C(Axios / Fetch)
70+
flowchart TB
71+
subgraph ClientContainer [Client Browser Container]
72+
SPA[React 19 SPA]
73+
Apollo[Apollo Client Link Splitter]
74+
Axios[Axios / sendBeacon Client]
7475
end
7576
76-
subgraph Proxy [Gateway / Proxy Layer]
77-
D[Tomcat Static Mapping /static] -->|Serves Static Files| A
78-
E[Spring Router /graphql & /api/*]
77+
subgraph SecurityFilterLayer [Tomcat Servlet Security & Mapping Layer]
78+
CORS[CorsRegistry Filter Mappings]
79+
Limiter[Bucket4j Rate Limiting Interceptor]
80+
Dispatcher[Spring DispatcherServlet]
81+
SockHandler[GraphQlWebSocketHandler]
7982
end
8083
81-
B -->|POST /graphql| E
82-
C -->|GET & PUT /api/*| E
84+
subgraph ControllerLayer [Controller Endpoint Mappings]
85+
REST[REST API Endpoints: Coffee, Donate, Activity]
86+
GraphQL[GraphQL Engine Mappings: @QueryMapping, @MutationMapping]
87+
end
8388
84-
subgraph Backend [Spring Boot Backend Server]
85-
E -->|REST API Map| F[REST Controllers]
86-
E -->|GraphQL Engine Map| G[GraphQL Controllers]
89+
subgraph ServiceCore [Granular Backend Service & Cache Engines]
90+
GitService[GitDetailsService]
91+
CoffeeService[CoffeesService]
92+
CacheManager[In-Memory ConcurrentHashMap Cache Managers]
93+
GitRepoCache[GitRepoCacheService]
94+
GitProjCache[GitProjectCacheService]
95+
CoffeeCache[CoffeeCacheService]
96+
DonResolver[DonateItemsResolver]
97+
PortResolver[PortfolioItemsResolver]
98+
Sink[Reactor Sinks.Many Multicast Channel]
99+
end
87100
88-
F -->|Bypass Engine| H[Service Layer]
89-
G -->|Resolve Mapping| H
101+
subgraph Datastore [Classpath JSON Datastore Layer]
102+
DiskDonate[(json/donate-items.json)]
103+
DiskBrews[(json/brews.json)]
104+
DiskPortfolio[(json/portfolio-items.json)]
105+
DiskWhitelist[(graphql/charities.txt)]
106+
end
90107
91-
H -->|Thread-Safe Write/Read| I[(In-Memory Cache Services)]
92-
H -->|Load Classpath Assets| J[(Local JSON Datastores)]
108+
subgraph External [External Network boundaries]
109+
AWS[AWS Secrets Manager API]
110+
GitAPI[GitHub REST API v3]
111+
CoffeeAPI[Third-Party Coffee REST / GraphQL APIs]
93112
end
94113
95-
H -->|Query Secret Keys| K[AWS Secrets Manager]
96-
H -->|Scheduled Fetch API| L[GitHub API / Ext. Coffee APIs]
114+
SPA -->|GraphQL Queries| Apollo
115+
SPA -->|HTTP / Telemetry Beacons| Axios
116+
117+
Apollo -->|POST /graphql| CORS
118+
Apollo -->|WS ws://localhost:8080/graphql| CORS
119+
Axios -->|PUT/GET /api/*| CORS
120+
121+
CORS --> Limiter
122+
Limiter --> Dispatcher
123+
Limiter --> SockHandler
124+
125+
Dispatcher --> REST
126+
Dispatcher --> GraphQL
127+
SockHandler --> GraphQL
128+
129+
REST --> GitService
130+
REST --> CoffeeService
131+
GraphQL --> DonResolver
132+
GraphQL --> PortResolver
133+
GraphQL --> Sink
134+
135+
GitService --> GitRepoCache
136+
GitService --> GitProjCache
137+
CoffeeService --> CoffeeCache
138+
139+
GitRepoCache --> CacheManager
140+
GitProjCache --> CacheManager
141+
CoffeeCache --> CacheManager
142+
143+
DonResolver --> DiskDonate
144+
DonResolver --> DiskWhitelist
145+
PortResolver --> DiskPortfolio
146+
147+
GitService -->|GET Request / Bearer Token| GitAPI
148+
GitService -->|Query Access Tokens| AWS
149+
CoffeeService -->|GET Request| CoffeeAPI
150+
```
151+
152+
### 2. Comprehensive UX Journey Flow
153+
This flowchart maps the sequential UX transitions, modal interactions, loading states, and live interface updates available to the user.
154+
155+
```mermaid
156+
flowchart TD
157+
Start([User Opens App]) --> Home[Renders Landing Page - Consistent Navy Theme]
158+
159+
Home --> NavProjects{Navigates App}
160+
161+
%% Projects UX Flow
162+
NavProjects -->|Projects Link| Projects[Renders RepoDetails]
163+
Projects --> LoadProjects[Check Cached Repository Data]
164+
LoadProjects -->|Miss / Load| ShowSpinner1[Display LoadingSpinner]
165+
ShowSpinner1 --> Hydrated1[Render Grid Cards with Repo Details]
166+
LoadProjects -->|Hit| Hydrated1
167+
Hydrated1 --> ClickRepo[User Clicks Specific Repo Card]
168+
ClickRepo --> Issues[Open RepoIssues Backlog]
169+
Issues --> Recharts[Display Interactive Recharts Bar Chart of Active Issues]
170+
171+
%% Brews UX Flow
172+
NavProjects -->|Brews Link| CoffeeHome[Renders CoffeeHome]
173+
CoffeeHome --> LoadRecipes[Check In-Memory CoffeeCacheService]
174+
LoadRecipes -->|Miss| GetExtRecipes[Fetch Recipes from External Coffee API]
175+
GetExtRecipes --> JacksonParser[Deserialize & Map to CoffeeDomain via Jackson]
176+
JacksonParser --> Hydrated2[Render Coffee Carousel with preparation cards]
177+
LoadRecipes -->|Hit| Hydrated2
178+
179+
%% Donate UX Flow
180+
NavProjects -->|Donate Link| Donate[Renders Donate Carousel]
181+
Donate --> HydrateDonate[Execute GET_DONATE_ITEMS Query]
182+
HydrateDonate --> LoadWhitelist[Filter On-Disk Charities via charities.txt Allowed List]
183+
LoadWhitelist --> RenderCarousel[Render Red Carousel Cards with Verified Charities]
184+
185+
RenderCarousel --> OpenModal[User Clicks 'Add Charity' Button]
186+
OpenModal --> InputDetails[Input Charity Details in Registration Form]
187+
InputDetails --> ValidateForm{Form Fields Validated?}
188+
189+
ValidateForm -->|Invalid format/year/protocol| FormError[Display Specific Warning message inside form]
190+
FormError --> InputDetails
191+
192+
ValidateForm -->|Valid details| DispatchMutation[Submit addCharityOption Mutation to GraphQL Server]
193+
DispatchMutation --> CheckServerWhitelist{Name is Whitelisted in charities.txt?}
194+
195+
CheckServerWhitelist -->|No / Fraud attempt| ServerError[Reject transaction & throw Validation error]
196+
ServerError --> Donate
197+
198+
CheckServerWhitelist -->|Yes| PersistServer[Append details to json/donate-items.json]
199+
PersistServer --> SinkEmit[Emit next charity to Multicast Sink]
200+
201+
SinkEmit --> PushWS[Push Event pushed instantly over ws://localhost:8080/graphql]
202+
PushWS --> UpdateState[Client subscription state appends new card dynamically]
203+
UpdateState --> RenderCarousel
97204
```
98205

99-
### 2. Donate Subsystem: Mutation & WebSocket Broadcast Sequence
206+
### 3. Donate Subsystem: Mutation & WebSocket Broadcast Sequence
100207
This sequence diagram tracks the full transactional life cycle when a user registers a new charity, from validation to real-time sync.
101208

102209
```mermaid
@@ -137,7 +244,7 @@ sequenceDiagram
137244
end
138245
```
139246

140-
### 3. Brews/Coffee Retrieval & Caching Flow
247+
### 4. Brews/Coffee Retrieval & Caching Flow
141248
This sequence diagram details the fallback and deserialization pipeline when querying coffee brewing instructions.
142249

143250
```mermaid
@@ -274,7 +381,7 @@ The frontend is built using **React 19 (ES6+)** as a Single-Page Application (SP
274381
| |
275382
v (Static/View routes) v (Dynamic/Functional routes)
276383
+---------+---------+ +---------+---------+
277-
|Static Presentation| | State & API Driven|
384+
| Static Presentation | | State & API Driven |
278385
+---------+---------+ +---------+---------+
279386
| |
280387
+-------------+-------------+ +-------------+-------------+
@@ -308,16 +415,16 @@ The backend uses a service-driven, cache-optimized structure to coordinate Sprin
308415
| | | |
309416
v v v v
310417
+--------------+--------------+ +--------+--------+ +-------------+-------------+ +--+----------------+
311-
| GitDetailsService | | BrewsResolver | | DonateItemsResolver | |ActivityTracking |
312-
| - Coordinates git calls | | - Loads brews | | - Loads, validates, lists | | Service |
313-
| - Thread-safe repository | | local JSON | | permitted charities | | - Receives click |
314-
+--------------+--------------+ +--------+--------+ +-------------+-------------+ | beacons |
418+
| GitDetailsService | | BrewsResolver | | DonateItemsResolver | |ActivityTracking |
419+
| - Coordinates git calls | | - Loads brews | | - Loads, validates, lists | | Service |
420+
| - Thread-safe repository | | local JSON | | permitted charities | | - Receives click|
421+
+--------------+--------------+ +--------+--------+ +-------------+-------------+ | beacons |
315422
| | | +--+----------------+
316423
+------+------+ v v |
317424
| | +-----------------+ +-----------------+ v
318-
v v | Brews Datastore| | Charity Files | +------+-------+
425+
v v | Brews Datastore| | Charity Files | +------+------+
319426
+-----+---+ +-----+---+ | (json/brews.json| | (charities.txt | | Activity |
320-
|GitRepo | | GitProj | +-----------------+ | donate-items) | | Datastore |
427+
|GitRepo | |GitProj | +-----------------+ | donate-items) | | Datastore |
321428
| Cache | | Cache | +-----------------+ +--------------+
322429
+---------+ +---------+
323430
```
@@ -391,7 +498,7 @@ The coffee subsystem coordinates external APIs, in-memory caches, local configur
391498
- **Cache Miss (GraphQL Pathway)**: Alternatively, the controller can call `getCoffeeDetailsGraphQl()`, which runs `GraphQLClientService.fetchCoffeeDetails()`. This service uses `RestTemplate` to send a structured GraphQL query to a coffee API.
392499
3. **Data Deserialization & Mapping**:
393500
- Raw responses contain ingredients as raw text arrays. The application uses a custom **Jackson Deserializer** (`IngredientsDeserializer`) to clean and format the ingredients into standardized list models.
394-
- The parsed details are mapped to Java `CoffeeDomain` objects.
501+
- The parsed details are mapped to Java `CoffeeDomain` object models.
395502
4. **Cache Hydration**: The populated `CoffeeDomain` list is stored in `CoffeeCacheService` and returned to the client browser as a JSON array.
396503
5. **UI Rendering**: The React component renders the updated data into interactive card layouts using the `CoffeeCarousel` component.
397504

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,15 @@ integration to provide value to users.
4949
</div>
5050
</a>
5151

52+
---
53+
54+
## 📐 Full Stack Architecture & System Design
55+
For a comprehensive architectural blueprint, including **C4 System Design Blueprints**, **Comprehensive UX Journey Diagrams**, granular backend service breakdowns, and data flow sequence mapping for dynamic features (such as **Subscriptions** and **Caching**), please refer to the:
56+
57+
👉 **[Architecture Documentation & Data Flows (ARCHITECTURE.md)](./ARCHITECTURE.md)**
58+
59+
---
60+
5261
## See ironoc-frontend README [here](./frontend/README.md)
5362

5463
## Basic request rate limiting

0 commit comments

Comments
 (0)