How ceas-ambassadors/ceas-ambassadors-website works
1. Overall shape
- This is a server-rendered Node.js web application for the CEAS Ambassadors organization.
- It follows a fairly classic Express MVC structure: HTTP routes call controllers, controllers use models, and views are rendered with Pug templates.
2. Request entrypoint and runtime
- bin/www is the executable entrypoint used to start the HTTP server.
- app.js wires together the Express app, middleware, route registration, error handling, and static file serving.
- The app is deployed as a typical Node service, with procfile indicating a process-managed runtime.
3. Presentation layer
- The UI is generated on the server with Pug templates in views/.
- Shared layout and reusable fragments live in views/layout.pug and views/partials/.
- Feature-specific page sets are organized by domain: views/event/, views/member/, plus standalone pages like calendar.pug, apply.pug, training.pug, and virtual-tour.pug.
4. Routing boundary
- Route modules in routes/ split the web surface into three main areas:
- routes/index.js for general site pages
- routes/event.js for tour/event functionality
- routes/member.js for member-related flows
- These route modules are the HTTP boundary between incoming requests and business logic.
5. Controller layer
- controllers/ contains the application logic for each domain area:
- controllers/index.js
- controllers/event.js
- controllers/member.js
- Controllers orchestrate reads/writes and decide which view to render, keeping route handlers thin.
6. Domain and persistence layer
- models/ contains the data access and domain objects:
- event.js
- member.js
- attendance.js
- session.js
- index.js as the model bootstrap/aggregation point
- The repository docs indicate a MySQL-backed database, with schema details in docs/database.md.
- migrations/ contains schema evolution support, including a one-time upgrade script from 1.x.x to 2.0.0.
7. Main business domains
- The app centers on three operational workflows:
- Event/tour management: listing, creating, and viewing tours/events
- Member management: profiles, signup/login, settings, and admin-style lists
- Attendance/progress tracking: members sign up for tours and track requirements/points/status
- Views like event/detail, event/list, member/profile, member/points-table, and attendanceStatus show these are first-class concepts.
8. Authentication and session state
- models/session.js suggests persistent or structured session handling for logged-in users.
- Member flows include login, signup, reset, and settings, so the system likely maintains authenticated user state across requests.
- This is an important boundary for the architecture diagram: some routes are public, while member/admin actions depend on session context.
9. Static assets and public content
- public/ contains the client-facing static assets: stylesheets and images.
- public/stylesheets/style.css is the primary visible styling hook.
- These assets are served directly by the Express app rather than through the controller/model stack.
10. Operational and maintenance tooling
- docs/ contains the repo’s operational knowledge:
- dev-guide.md for local setup
- production.md for server management
- database.md for schema and MySQL connectivity
- tools/db_backup.sh indicates a maintenance workflow for backing up the database.
11. Testing and verification
- test/ includes coverage for the main functional areas: account, attendance, event, member, and basic app behavior.
- CI is set up through GitHub Actions (.github/workflows/project.yml) and legacy Travis config (.travis.yml), showing the repository expects automated validation on change.
12. External dependencies and integration points
- The key external dependency is the MySQL database.
- The site is intended for the University of Cincinnati CEAS Ambassadors program, but the main architectural boundary is internal: browser users interact with the server-rendered app, which persists operational data in MySQL.
13. How data typically flows
- A browser request hits Express → a route module selects a controller action → the controller reads/writes through a model → the model talks to MySQL → the controller renders a Pug view with returned data → HTML is sent back to the browser.
- Static content bypasses this flow and is served from public/.
14. What to emphasize in an architecture diagram
- Draw four main layers: web client, Express app (routes/controllers), domain/data models, and MySQL database.
- Show the Pug view renderer as part of the server-side presentation layer.
- Include the separate operational path for migrations/backups/docs/tests, since these support the system but are not part of runtime request handling.
Main entry points: app.js App · views Views · event.js Event ctrl · member.js Member ctrl
Components 31
Runtime
Server startup and request handling
Presentation
Server-rendered pages and static assets
- Views · Server-rendered pages and shared fragments
views - Layout · Shared page shell
views/layout.pug - Partials · Reusable UI fragments
views/partials - Event pages · Event listing, detail, create, and attendance pages
views/event - Member pages · Login, signup, profile, and settings pages
views/member - Public assets · CSS and images served directly by Express
public
Domain
Routes, controllers, and models
- Routes · Request routing for site areas
- Site routes · General pages and shared site surface
routes/index.js - Event routes · Tour and event request handling
routes/event.js - Member routes · Member account request handling
routes/member.js - Controllers · Orchestrate domain actions and view selection
- Site ctrl · General page actions
controllers/index.js - Event ctrl · Event and attendance actions
controllers/event.js - Member ctrl · Member account and profile actions
controllers/member.js - Models · Domain objects and persistence access
- Model index · Model aggregation and initialization
models/index.js - Event model · Event and tour data access
models/event.js - Member model · Member account data access
models/member.js - Attendance · Signups, points, and attendance tracking
models/attendance.js - Session model · Logged-in session state management
models/session.js
Operations
Docs, tests, migrations, and maintenance
- Migrations · Database upgrade scripts and migration notes
migrations - Docs · Development, production, and database guidance
docs - Tests · Functional coverage for app, account, event, member, and attendance
test - Backup tool · Database backup script
tools/db_backup.sh - CI · GitHub Actions and legacy Travis validation
Other components
- Browser · End users accessing the site
- MySQL · Persistent backend database
Connections 41
- Browser → App: HTTP requests · Browser traffic enters the Express application
- Procfile → www: start command · Process manager launches the server entrypoint
- www → App: boot · Server entrypoint initializes the Express app
- App → Routes: registers · Express mounts the route modules
- App → Public assets: serves · Static files bypass controller logic
- App → Views: renders · View engine produces HTML responses
- App → Config: loads · Application behavior is configured from settings
- Routes → Site routes: includes · General site routing
- Routes → Event routes: includes · Event and tour routing
- Routes → Member routes: includes · Member account routing
- Site routes → Site ctrl: delegates to · Route handlers call site controller actions
- Event routes → Event ctrl: delegates to · Route handlers call event controller actions
- Member routes → Member ctrl: delegates to · Route handlers call member controller actions
- Controllers → Site ctrl: includes · Site controller module
- Controllers → Event ctrl: includes · Event controller module
- Controllers → Member ctrl: includes · Member controller module
- Site ctrl → Views: renders pages · General pages are rendered through Pug templates
- Event ctrl → Event pages: renders pages · Event workflows render event templates
- Member ctrl → Member pages: renders pages · Member workflows render member templates
- Event ctrl → Event model: uses · Event actions read and write event data
- Event ctrl → Attendance: uses · Attendance and signup logic
- Member ctrl → Member model: uses · Member actions read and write member data
- Member ctrl → Session model: uses · Authentication and session state
- Site ctrl → Model index: uses · Shared model initialization and access
- Model index → Models: aggregates · Model bootstrap groups persistence components
- Models → Event model: includes · Event persistence layer
- Models → Member model: includes · Member persistence layer
- Models → Attendance: includes · Attendance persistence layer
- Models → Session model: includes · Session persistence layer
- Event model → MySQL: persists to · Event data stored in MySQL
- Member model → MySQL: persists to · Member data stored in MySQL
- Attendance → MySQL: persists to · Attendance data stored in MySQL
- Session model → MySQL: persists to · Session state stored in MySQL
- Views → Layout: shared shell · Common page layout
- Views → Partials: shared fragments · Reusable UI partials
- Views → Event pages: feature pages · Event-related templates
- Views → Member pages: feature pages · Member-related templates
- Docs → Migrations: supports · Documentation describes schema evolution and operations
- Tests → Controllers: verifies · Tests cover major application workflows
- CI → Tests: runs · Automation executes repository validation
- Backup tool → MySQL: backs up · Maintenance script targets the database