# oregon-mai/oregon-frontend architecture

> Architecture diagram of the GitHub repository oregon-mai/oregon-frontend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oregon-mai/oregon-frontend
- Repository: https://github.com/oregon-mai/oregon-frontend

## Overview

#### Purpose and runtime

T1 Workspace is a Vite/React TypeScript frontend for employee desk booking. It runs locally through the Vite dev server and currently uses a stub authentication flow; no backend implementation is present. Browser `localStorage` persists the JWT token.

Entry bootstrap and route/provider composition are in `src/main.tsx`; global styling begins in `src/index.css`.

#### Application shell and navigation

The authenticated workspace is organized around a shared layout that supplies the top bar, navigation sidebar, and page content area:

- `src/components/Layout.tsx`
- `src/components/Sidebar.tsx`
- `src/components/Layout.module.css`

The sidebar is also the floor/navigation and “today” booking summary boundary. The principal protected destination is the office map page at `/map`.

#### Authentication boundary

Authentication is modeled as a global React context holding the current user and bookings:

- `src/context/AuthContext.tsx`
- `src/types/auth.ts`

`src/api/authApi.ts` defines the login API boundary (`POST /auth/login`), while the current README-described behavior is a client-side stub accepting an email and password of at least six characters. Login UI lives in `src/pages/LoginPage.tsx`.

Access control is enforced at routing level by `src/components/ProtectedRoute.tsx`, which checks for the stored token and redirects unauthenticated users away from `/map` to `/login`.

#### Route and session flow

1. `src/main.tsx` initializes React routing and wraps routes in `AuthProvider`.
2. A user submits credentials on `src/pages/LoginPage.tsx`.
3. The login page calls `src/api/authApi.ts`; successful authentication updates `AuthContext` and stores the token in browser storage.
4. `ProtectedRoute` permits access to `src/pages/MapPage.tsx` only with an authenticated token.
5. Logout from the shared layout clears session state/token and returns the user to the public login flow.

#### Office map domain

The office visualization and booking domain types are separated from rendering:

- `src/types/map.ts`
- `src/pages/MapPage.tsx`
- `src/components/OfficeMap/OfficeMap.tsx`

`MapPage` composes the workspace view. `OfficeMap` renders desks grouped by zones and exposes desk status distinctions: available, occupied, and booked by the current user. Domain structures include desks, zones, and bookings, enabling the map to remain a presentation/selection layer rather than own authentication state.

#### Booking interaction flow

Selecting a bookable desk on the map feeds the booking panel:

- `src/components/OfficeMap/OfficeMap.tsx`
- `src/components/BookingPanel/BookingPanel.tsx`
- `src/context/AuthContext.tsx`

`BookingPanel` presents 15-minute reservation slots. Booking changes are maintained in `AuthContext`, making them available both to the map (for desk status) and sidebar/widget views (for today’s reservations). This is currently client-side shared state; no booking API or persistence service is represented in the repository.

#### Key boundaries and extension points

The repository separates external authentication integration (`src/api/authApi.ts`) from session state (`src/context/AuthContext.tsx`), and map domain contracts (`src/types/map.ts`) from visual components. A production backend can replace the auth stub and add booking/map data APIs without changing route protection or the broad page composition. The material platform dependencies are React, TypeScript, Vite, browser routing, and `localStorage`; no server runtime, database, or external infrastructure is included.

Main entry points: [`src/context/AuthContext.tsx`](https://github.com/oregon-mai/oregon-frontend/blob/main/src/context/AuthContext.tsx) (Auth context), [`src/main.tsx`](https://github.com/oregon-mai/oregon-frontend/blob/main/src/main.tsx) (App bootstrap), [`src/pages/MapPage.tsx`](https://github.com/oregon-mai/oregon-frontend/blob/main/src/pages/MapPage.tsx) (Map page), [`src/components/ProtectedRoute.tsx`](https://github.com/oregon-mai/oregon-frontend/blob/main/src/components/ProtectedRoute.tsx) (Protected route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Frontend runtime"]
  node_vite{{"Vite dev server<br/>runtime"}}
  node_main["App bootstrap<br/>React entry<br/>[main.tsx]"]
  node_styles["Global styles<br/>CSS<br/>[index.css]"]
end

subgraph group_auth["Authentication"]
  node_login["Login page<br/>public route<br/>[LoginPage.tsx]"]
  node_auth_api["Auth API boundary<br/>API client<br/>[authApi.ts]"]
  node_auth_context["Auth context<br/>React context<br/>[AuthContext.tsx]"]
  node_auth_types["Auth contracts<br/>TypeScript types<br/>[auth.ts]"]
  node_storage[("Browser localStorage<br/>browser storage")]
end

subgraph group_workspace["Protected workspace"]
  node_protected_route["Protected route<br/>route guard<br/>[ProtectedRoute.tsx]"]
  node_layout["Workspace layout<br/>shared shell<br/>[Layout.tsx]"]
  node_sidebar["Sidebar<br/>navigation widget<br/>[Sidebar.tsx]"]
end

subgraph group_map["Office booking"]
  node_map_page["Map page<br/>protected route<br/>[MapPage.tsx]"]
  node_office_map["Office map<br/>map renderer<br/>[OfficeMap.tsx]"]
  node_booking_panel["Booking panel<br/>reservation UI<br/>[BookingPanel.tsx]"]
  node_map_types["Map contracts<br/>TypeScript types<br/>[map.ts]"]
end

node_vite -->|"serves"| node_main
node_main -->|"loads"| node_styles
node_main -->|"wraps with provider"| node_auth_context
node_main -->|"routes /login"| node_login
node_main -->|"guards /map"| node_protected_route
node_login -->|"submits credentials"| node_auth_api
node_auth_api -->|"returns authenticated session"| node_auth_context
node_auth_context -->|"stores token"| node_storage
node_protected_route -->|"checks token"| node_storage
node_protected_route -->|"permits authenticated access"| node_map_page
node_protected_route -.->|"redirects when absent"| node_login
node_auth_context -->|"uses"| node_auth_types
node_map_page -->|"renders within"| node_layout
node_layout -->|"includes"| node_sidebar
node_map_page -->|"composes"| node_office_map
node_map_page -->|"composes"| node_booking_panel
node_office_map -->|"selected desk"| node_booking_panel
node_office_map -->|"reads booking state"| node_auth_context
node_booking_panel -->|"updates bookings"| node_auth_context
node_sidebar -->|"reads today's bookings"| node_auth_context
node_layout -->|"logout clears session"| node_auth_context
node_office_map -->|"uses desk and zone contracts"| node_map_types
node_map_page -->|"uses booking contracts"| node_map_types

click node_main "https://github.com/oregon-mai/oregon-frontend/blob/main/src/main.tsx"
click node_styles "https://github.com/oregon-mai/oregon-frontend/blob/main/src/index.css"
click node_login "https://github.com/oregon-mai/oregon-frontend/blob/main/src/pages/LoginPage.tsx"
click node_auth_api "https://github.com/oregon-mai/oregon-frontend/blob/main/src/api/authApi.ts"
click node_auth_context "https://github.com/oregon-mai/oregon-frontend/blob/main/src/context/AuthContext.tsx"
click node_auth_types "https://github.com/oregon-mai/oregon-frontend/blob/main/src/types/auth.ts"
click node_protected_route "https://github.com/oregon-mai/oregon-frontend/blob/main/src/components/ProtectedRoute.tsx"
click node_layout "https://github.com/oregon-mai/oregon-frontend/blob/main/src/components/Layout.tsx"
click node_sidebar "https://github.com/oregon-mai/oregon-frontend/blob/main/src/components/Sidebar.tsx"
click node_map_page "https://github.com/oregon-mai/oregon-frontend/blob/main/src/pages/MapPage.tsx"
click node_office_map "https://github.com/oregon-mai/oregon-frontend/blob/main/src/components/OfficeMap/OfficeMap.tsx"
click node_booking_panel "https://github.com/oregon-mai/oregon-frontend/blob/main/src/components/BookingPanel/BookingPanel.tsx"
click node_map_types "https://github.com/oregon-mai/oregon-frontend/blob/main/src/types/map.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_vite,node_main,node_styles toneBlue
class node_login,node_auth_api,node_auth_context,node_auth_types,node_storage toneAmber
class node_protected_route,node_layout,node_sidebar toneMint
class node_map_page,node_office_map,node_booking_panel,node_map_types toneRose
```

## Components

### Frontend runtime

- **Vite dev server**: runtime · Serves the React frontend locally.
- [App bootstrap](https://github.com/oregon-mai/oregon-frontend/blob/main/src/main.tsx): React entry · Composes routing and AuthProvider. · `src/main.tsx`
- [Global styles](https://github.com/oregon-mai/oregon-frontend/blob/main/src/index.css): CSS · `src/index.css`

### Authentication

- [Login page](https://github.com/oregon-mai/oregon-frontend/blob/main/src/pages/LoginPage.tsx): public route · `src/pages/LoginPage.tsx`
- [Auth API boundary](https://github.com/oregon-mai/oregon-frontend/blob/main/src/api/authApi.ts): API client · Currently implements the client-side login stub. · `src/api/authApi.ts`
- [Auth context](https://github.com/oregon-mai/oregon-frontend/blob/main/src/context/AuthContext.tsx): React context · Holds current user and shared bookings. · `src/context/AuthContext.tsx`
- [Auth contracts](https://github.com/oregon-mai/oregon-frontend/blob/main/src/types/auth.ts): TypeScript types · `src/types/auth.ts`
- **Browser localStorage**: browser storage · Persists the JWT token.

### Protected workspace

- [Protected route](https://github.com/oregon-mai/oregon-frontend/blob/main/src/components/ProtectedRoute.tsx): route guard · Redirects unauthenticated map access to login. · `src/components/ProtectedRoute.tsx`
- [Workspace layout](https://github.com/oregon-mai/oregon-frontend/blob/main/src/components/Layout.tsx): shared shell · Supplies top bar, sidebar, and page area. · `src/components/Layout.tsx`
- [Sidebar](https://github.com/oregon-mai/oregon-frontend/blob/main/src/components/Sidebar.tsx): navigation widget · Shows floor navigation and today's bookings. · `src/components/Sidebar.tsx`

### Office booking

- [Map page](https://github.com/oregon-mai/oregon-frontend/blob/main/src/pages/MapPage.tsx): protected route · Composes the desk-booking workspace at /map. · `src/pages/MapPage.tsx`
- [Office map](https://github.com/oregon-mai/oregon-frontend/blob/main/src/components/OfficeMap/OfficeMap.tsx): map renderer · Renders zoned desks and their booking status. · `src/components/OfficeMap/OfficeMap.tsx`
- [Booking panel](https://github.com/oregon-mai/oregon-frontend/blob/main/src/components/BookingPanel/BookingPanel.tsx): reservation UI · Offers 15-minute reservation slots. · `src/components/BookingPanel/BookingPanel.tsx`
- [Map contracts](https://github.com/oregon-mai/oregon-frontend/blob/main/src/types/map.ts): TypeScript types · Defines desks, zones, and bookings. · `src/types/map.ts`

## Connections

- Vite dev server → App bootstrap: serves
- App bootstrap → Global styles: loads
- App bootstrap → Auth context: wraps with provider
- App bootstrap → Login page: routes /login
- App bootstrap → Protected route: guards /map
- Login page → Auth API boundary: submits credentials
- Auth API boundary → Auth context: returns authenticated session
- Auth context → Browser localStorage: stores token
- Protected route → Browser localStorage: checks token
- Protected route → Map page: permits authenticated access
- Protected route → Login page: redirects when absent
- Auth context → Auth contracts: uses
- Map page → Workspace layout: renders within
- Workspace layout → Sidebar: includes
- Map page → Office map: composes
- Map page → Booking panel: composes
- Office map → Booking panel: selected desk
- Office map → Auth context: reads booking state
- Booking panel → Auth context: updates bookings
- Sidebar → Auth context: reads today's bookings
- Workspace layout → Auth context: logout clears session
- Office map → Map contracts: uses desk and zone contracts
- Map page → Map contracts: uses booking contracts