# phurinkaewpuangsek/perimeter architecture

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

- Interactive diagram: https://gitdiagram.com/phurinkaewpuangsek/perimeter
- Repository: https://github.com/phurinkaewpuangsek/perimeter

## Overview

Perimeter is an indoor wayfinding and room/schedule service for the LC-3 building. Visitors search rooms or exams, inspect interactive floor maps, and can request routes that account for temporary closures; signed-in users can save schedules, while staff and admins manage building data and users. The React client talks to serverless API functions backed by DynamoDB, with Cognito providing authentication and role information. The graph preserves the README’s documented capabilities, but several frontend and backend connections are documented rather than verified from sampled implementation excerpts.

Main entry points: [`frontend/src/main.tsx`](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/main.tsx) (Route application), [`frontend/src/components/LandingPage.tsx`](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/components/LandingPage.tsx) (Room and exam search), [`frontend/src/components/MapPage.tsx`](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/components/MapPage.tsx) (Interactive map), [`functions/get-route/index.mjs`](https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/get-route/index.mjs) (Route endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Route application<br/>[main.tsx]"]
  node_landing["Room and exam search<br/>[LandingPage.tsx]"]
  node_map["Interactive map<br/>[MapPage.tsx]"]
  node_mapview["Floor map renderer<br/>[MapContainer.tsx]"]
  node_pinstate["Pin state provider<br/>[PinsProvider.tsx]"]
  node_calendar["Calendar export and sync<br/>[calendarExport.ts]"]
end

subgraph group_domain["Search and navigation"]
  node_examsearch["Exam search<br/>[useExamSearch.ts]"]
  node_roomdata["Room data hook<br/>[useRooms.ts]"]
  node_scheduledata["Schedule data hook<br/>[useSchedules.ts]"]
  node_roomsearch["Room filtering<br/>[filterRooms.ts]"]
  node_routeservice["Route client<br/>[routeService.ts]"]
end

subgraph group_identity["Identity and administration"]
  node_auth["Cognito sign-in<br/>[authService.ts]"]
  node_guard["Role route guard<br/>[RouteGuard.tsx]"]
  node_cognito{{"Cognito User Pool"}}
end

subgraph group_backend["Serverless API"]
  node_routeapi["Route endpoint<br/>[index.mjs]"]
  node_routeengine["Dijkstra routing<br/>[route.mjs]"]
  node_graphapi["Graph endpoint<br/>[index.mjs]"]
  node_closureapi["Closure updates<br/>[index.mjs]"]
  node_locationapi["Location API<br/>[index.mjs]"]
  node_scheduleapi["Schedule API<br/>[index.mjs]"]
  node_pins["Personal pins API<br/>[index.mjs]"]
  node_pinwrites["Pin mutations<br/>[index.mjs]"]
  node_schedulewrites["Schedule mutations<br/>[index.mjs]"]
  node_management["Staff data management<br/>[adminService.ts]"]
  node_users["User administration<br/>[index.mjs]"]
  node_gateway{{"API Gateway"}}
end

subgraph group_data["Persistent data"]
  node_locationsdb[("Locations table")]
  node_schedulesdb[("Schedules table")]
  node_pinsdb[("Pins table")]
  node_graphdb[("Graph table")]
end

node_visitor(("Visitor"))
node_signeduser(("Signed-in user"))
node_staffadmin(("Staff / admin"))
node_googlecal{{"Google Calendar"}}

node_visitor -->|"opens"| node_app
node_signeduser -.->|"opens"| node_app
node_staffadmin -->|"opens console"| node_app
node_app -->|"routes to"| node_landing
node_app -->|"routes to"| node_map
node_app -->|"protects staff routes"| node_guard
node_app -->|"provides state"| node_pinstate
node_landing -->|"loads rooms"| node_roomdata
node_landing -->|"loads schedules"| node_scheduledata
node_landing -->|"searches exams"| node_examsearch
node_examsearch -->|"finds exam matches"| node_roomsearch
node_map -->|"renders map"| node_mapview
node_map -->|"requests routes"| node_routeservice
node_roomdata -.->|"fetches rooms"| node_locationapi
node_scheduledata -->|"fetches schedules"| node_scheduleapi
node_routeservice -->|"requests route"| node_gateway
node_gateway -->|"dispatches"| node_routeapi
node_routeapi -->|"calls"| node_routeengine
node_gateway -->|"dispatches"| node_graphapi
node_gateway -->|"dispatches"| node_locationapi
node_gateway -->|"dispatches"| node_scheduleapi
node_gateway -->|"dispatches"| node_pins
node_gateway -->|"dispatches"| node_pinwrites
node_gateway -->|"dispatches"| node_schedulewrites
node_gateway -->|"dispatches"| node_closureapi
node_gateway -->|"dispatches"| node_users
node_routeapi -->|"reads graph"| node_graphdb
node_graphapi -->|"reads graph"| node_graphdb
node_closureapi -->|"writes closures"| node_graphdb
node_locationapi -->|"reads locations"| node_locationsdb
node_scheduleapi -->|"reads schedules"| node_schedulesdb
node_pins -->|"reads pins"| node_pinsdb
node_pinwrites -->|"writes pins"| node_pinsdb
node_schedulewrites -->|"writes schedules"| node_schedulesdb
node_auth -->|"authenticates"| node_cognito
node_guard -->|"checks roles"| node_auth
node_pinstate -->|"loads and saves"| node_pins
node_management -.->|"updates building data"| node_gateway
node_users -->|"manages accounts"| node_cognito
node_calendar -->|"syncs events"| node_googlecal

click node_app "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/main.tsx"
click node_landing "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/components/LandingPage.tsx"
click node_map "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/components/MapPage.tsx"
click node_mapview "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/components/map/MapContainer.tsx"
click node_examsearch "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/hooks/useExamSearch.ts"
click node_roomdata "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/hooks/useRooms.ts"
click node_scheduledata "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/hooks/useSchedules.ts"
click node_roomsearch "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/services/filterRooms.ts"
click node_routeservice "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/services/routeService.ts"
click node_routeapi "https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/get-route/index.mjs"
click node_routeengine "https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/get-route/route.mjs"
click node_graphapi "https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/get-graph/index.mjs"
click node_closureapi "https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/update-closure/index.mjs"
click node_locationapi "https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/get-locations/index.mjs"
click node_scheduleapi "https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/get-schedules/index.mjs"
click node_pins "https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/get-pins/index.mjs"
click node_pinwrites "https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/create-pin/index.mjs"
click node_schedulewrites "https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/create-schedule/index.mjs"
click node_management "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/services/adminService.ts"
click node_users "https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/manage-users/index.mjs"
click node_auth "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/services/authService.ts"
click node_guard "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/components/RouteGuard.tsx"
click node_pinstate "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/context/PinsProvider.tsx"
click node_calendar "https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/services/calendarExport.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_app,node_landing,node_map,node_mapview,node_pinstate,node_calendar,node_signeduser toneBlue
class node_examsearch,node_roomdata,node_scheduledata,node_roomsearch,node_routeservice toneAmber
class node_auth,node_guard,node_cognito toneMint
class node_routeapi,node_routeengine,node_graphapi,node_closureapi,node_locationapi,node_scheduleapi,node_pins,node_pinwrites,node_schedulewrites,node_management,node_users,node_gateway toneRose
class node_locationsdb,node_schedulesdb,node_pinsdb,node_graphdb,node_visitor,node_staffadmin,node_googlecal toneIndigo
```

## Components

### Web client

- [Route application](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Room and exam search](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/components/LandingPage.tsx): `frontend/src/components/LandingPage.tsx`
- [Interactive map](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/components/MapPage.tsx): `frontend/src/components/MapPage.tsx`
- [Floor map renderer](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/components/map/MapContainer.tsx): `frontend/src/components/map/MapContainer.tsx`
- [Pin state provider](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/context/PinsProvider.tsx): `frontend/src/context/PinsProvider.tsx`
- [Calendar export and sync](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/services/calendarExport.ts): `frontend/src/services/calendarExport.ts`

### Search and navigation

- [Exam search](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/hooks/useExamSearch.ts): `frontend/src/hooks/useExamSearch.ts`
- [Room data hook](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/hooks/useRooms.ts): `frontend/src/hooks/useRooms.ts`
- [Schedule data hook](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/hooks/useSchedules.ts): `frontend/src/hooks/useSchedules.ts`
- [Room filtering](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/services/filterRooms.ts): `frontend/src/services/filterRooms.ts`
- [Route client](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/services/routeService.ts): `frontend/src/services/routeService.ts`

### Identity and administration

- [Cognito sign-in](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/services/authService.ts): `frontend/src/services/authService.ts`
- [Role route guard](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/components/RouteGuard.tsx): `frontend/src/components/RouteGuard.tsx`
- **Cognito User Pool**

### Serverless API

- [Route endpoint](https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/get-route/index.mjs): `functions/get-route/index.mjs`
- [Dijkstra routing](https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/get-route/route.mjs): `functions/get-route/route.mjs`
- [Graph endpoint](https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/get-graph/index.mjs): `functions/get-graph/index.mjs`
- [Closure updates](https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/update-closure/index.mjs): `functions/update-closure/index.mjs`
- [Location API](https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/get-locations/index.mjs): `functions/get-locations/index.mjs`
- [Schedule API](https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/get-schedules/index.mjs): `functions/get-schedules/index.mjs`
- [Personal pins API](https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/get-pins/index.mjs): `functions/get-pins/index.mjs`
- [Pin mutations](https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/create-pin/index.mjs): `functions/create-pin/index.mjs`
- [Schedule mutations](https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/create-schedule/index.mjs): `functions/create-schedule/index.mjs`
- [Staff data management](https://github.com/phurinkaewpuangsek/perimeter/blob/main/frontend/src/services/adminService.ts): `frontend/src/services/adminService.ts`
- [User administration](https://github.com/phurinkaewpuangsek/perimeter/blob/main/functions/manage-users/index.mjs): `functions/manage-users/index.mjs`
- **API Gateway**

### Persistent data

- **Locations table**
- **Schedules table**
- **Pins table**
- **Graph table**

### Other components

- **Visitor**
- **Signed-in user**
- **Staff / admin**
- **Google Calendar**

## Connections

- Visitor → Route application: opens (evidence: `frontend/src/main.tsx`)
- Signed-in user → Route application: opens
- Staff / admin → Route application: opens console (evidence: `frontend/src/main.tsx`)
- Route application → Room and exam search: routes to (evidence: `frontend/src/main.tsx`)
- Route application → Interactive map: routes to (evidence: `frontend/src/main.tsx`)
- Route application → Role route guard: protects staff routes (evidence: `frontend/src/main.tsx`)
- Route application → Pin state provider: provides state (evidence: `frontend/src/main.tsx`)
- Room and exam search → Room data hook: loads rooms (evidence: `frontend/src/components/LandingPage.tsx`)
- Room and exam search → Schedule data hook: loads schedules (evidence: `frontend/src/components/LandingPage.tsx`)
- Room and exam search → Exam search: searches exams (evidence: `frontend/src/components/LandingPage.tsx`)
- Exam search → Room filtering: finds exam matches (evidence: `frontend/src/hooks/useExamSearch.ts`)
- Interactive map → Floor map renderer: renders map (evidence: `frontend/src/components/MapPage.tsx`)
- Interactive map → Route client: requests routes (evidence: `frontend/src/components/MapPage.tsx`)
- Room data hook → Location API: fetches rooms
- Schedule data hook → Schedule API: fetches schedules (evidence: `frontend/src/hooks/useSchedules.ts`)
- Route client → API Gateway: requests route (evidence: `README.md`)
- API Gateway → Route endpoint: dispatches (evidence: `README.md`)
- Route endpoint → Dijkstra routing: calls (evidence: `functions/get-route/index.mjs`)
- API Gateway → Graph endpoint: dispatches (evidence: `README.md`)
- API Gateway → Location API: dispatches (evidence: `README.md`)
- API Gateway → Schedule API: dispatches (evidence: `README.md`)
- API Gateway → Personal pins API: dispatches (evidence: `README.md`)
- API Gateway → Pin mutations: dispatches (evidence: `README.md`)
- API Gateway → Schedule mutations: dispatches (evidence: `README.md`)
- API Gateway → Closure updates: dispatches (evidence: `README.md`)
- API Gateway → User administration: dispatches (evidence: `README.md`)
- Route endpoint → Graph table: reads graph (evidence: `README.md`)
- Graph endpoint → Graph table: reads graph (evidence: `README.md`)
- Closure updates → Graph table: writes closures (evidence: `README.md`)
- Location API → Locations table: reads locations (evidence: `README.md`)
- Schedule API → Schedules table: reads schedules (evidence: `README.md`)
- Personal pins API → Pins table: reads pins (evidence: `README.md`)
- Pin mutations → Pins table: writes pins (evidence: `README.md`)
- Schedule mutations → Schedules table: writes schedules (evidence: `README.md`)
- Cognito sign-in → Cognito User Pool: authenticates (evidence: `frontend/src/services/authService.ts`)
- Role route guard → Cognito sign-in: checks roles (evidence: `frontend/src/components/RouteGuard.tsx`)
- Pin state provider → Personal pins API: loads and saves (evidence: `frontend/src/context/PinsProvider.tsx`)
- Staff data management → API Gateway: updates building data
- User administration → Cognito User Pool: manages accounts (evidence: `README.md`)
- Calendar export and sync → Google Calendar: syncs events (evidence: `README.md`)