samuelfriher/ull-auditorium-seating

1. Overall shape

- This is a static Astro app with a vanilla TypeScript + DOM/SVG client architecture.

- There is no React/Vue component runtime; the UI is assembled directly through TypeScript classes that manipulate the DOM and SVG.

2. Application entry and pages

- src/pages/index.astro is the main application shell.

- src/pages/legal.astro provides the disclaimer/legal page referenced by the footer.

- src/main.ts is the client-side bootstrap for the interactive seating app.

3. Primary architectural pattern

- The app is organized as a decoupled MVC-like system:

- Controllers manage user actions and state changes.

- Views render UI and emit user events.

- Models hold domain state.

- Communication is mediated by a typed EventBus (src/events/EventBus.ts), which keeps views and controllers separated.

4. State and domain model

- src/models/AppState.ts appears to be the central application state container.

- The seating domain is modeled with:

- Venue, Section, Seat, SeatGroup

- GraduationGuestGroup

- VenueSerializer supports turning the full seating arrangement into/from a portable representation, enabling save/load workflows.

5. Venue definition and layout generation

- The auditorium layout is not hardcoded in a single view; it is generated from data modules in src/data/:

- UllAuditorium.ts

- AmphitheaterGenerator.ts

- BoxesGenerator.ts

- StallsGenerator.ts

- These generators define the physical structure of the venue, which is then consumed by the UI and allocation logic.

- VenueDefinitionLoader in src/utils/ likely bridges these definitions into runtime-ready models.

6. View layer responsibilities

- Views are split by responsibility and by screen area:

- src/views/venue/* renders the SVG seating map and seat/section interactions.

- src/views/groups/* manages group CRUD panels and list items.

- src/views/graduation/* contains the graduation/orla configuration UI.

- src/views/layout/* provides shared chrome such as toolbar and footer.

- The view layer is responsible for presentation and user interaction capture, not business logic.

7. Controller layer responsibilities

- Controllers orchestrate user workflows:

- AppController is the top-level coordinator.

- SelectionController handles seat selection behavior, including individual and drag selection.

- GroupController manages group create/edit/delete actions.

- GraduationController coordinates graduation mode configuration and allocation.

- ExportController handles import/export of seating state.

- Controllers are the main consumers of view events and the main mutators of application state.

8. Graduation mode as a distinct subsystem

- Graduation/orla functionality is a specialized workflow rather than a minor toggle.

- The subsystem combines:

- allocation logic in src/utils/GraduationAllocator.ts

- seat ordering in GraduationSeatSorter.ts

- location labeling in GraduationLocationLabeler.ts

- dedicated graduation views and panels

- This mode has its own data model (GraduationGuestGroup) and its own interaction flow, suggesting a bounded feature area inside the app.

9. Seat coloring, layout rules, and validation

- Several utility modules encode domain rules:

- ColorUtils and SeatColorResolver determine visual coloring for groups/selections.

- LayoutUtils and LayoutValidator ensure venue layouts are consistent and usable.

- These utilities sit between the raw venue definition and the rendered UI, preventing presentation logic from owning domain rules.

10. Data flow through the app

- A typical interaction flow is:

- user interacts with a view

- view emits an event on the EventBus

- controller updates AppState / domain objects

- utility logic validates or transforms data

- views re-render based on updated state

- Import/export and serialization provide another flow: current state → serializer/export controller → JSON file, and reverse on import.

11. Styling and assets

- Styling is split into focused CSS files under src/styles/ for main app, panels, venue rendering, and legal page.

- public/images/ holds static assets used by the site.

- Because the seating map is SVG-driven, styling is an important part of the functional UI, not just cosmetic layering.

12. Build, deployment, and quality tooling

- Astro handles static generation/building and the local dev server.

- CI/CD is automated via GitHub Actions in .github/workflows/deploy.yml, deploying to GitHub Pages on main.

- The repo includes strong test coverage with Vitest and mutation testing with Stryker, indicating the architecture is designed for logic-heavy, testable boundaries.

13. How to diagram the repository

- A good architecture diagram would show:

- Astro pages and bootstrap at the top

- EventBus in the middle as the communication backbone

- Controllers on one side, Views on the other, Models/Utilities beneath

- Venue generators feeding the domain model

- Export/import and graduation allocation as separate functional subsystems

- CSS/static assets as supporting presentation infrastructure

- GitHub Actions/GitHub Pages as the deployment boundary