Use Cases - COS301-SE-2025/Swift-Signals GitHub Wiki

👥 User Backgrounds

Swift Signals is built with two distinct user groups in mind, each defined by their background, expertise, and motivation for engaging with the platform:

🏛️ Traffic Departments

These users represent official entities responsible for managing and improving road traffic infrastructure. They are typically employed by municipalities, city councils, or government transport agencies.

Characteristics:

  • Operate in structured, regulatory environments.
  • Possess domain knowledge in traffic engineering and urban planning.
  • Prioritize reliability, accuracy, and measurable improvements in traffic flow.
  • Often work within teams, requiring collaboration and role-based system access.
  • Value data-driven decision-making and visual reporting to support operational planning.

🧠 Aspiring Traffic Engineers / Hobbyists

This group includes students, academic researchers, urban planning enthusiasts, and technology hobbyists with an interest in traffic optimization and simulation.

Characteristics:

  • Motivated by curiosity, learning, or personal interest in intelligent transport systems.
  • Come from varied technical backgrounds, ranging from engineering to data science.
  • Tend to explore systems in a self-directed, experimental manner.
  • Value intuitive interfaces, transparent models, and educational insights.
  • Are not bound by institutional constraints and often use the system informally.

🧩 Use Cases

🔐 Authentication & Account Management

All users should be able to:

  • 🔓 Register, log in, and log out of their accounts
  • 🛠️ Reset forgotten passwords
  • 🗑️ Delete their accounts if desired

🛠️ Creating Simulations

Users can create a simulation of a single traffic intersection. When creating a simulation, users will:

  • 🏙️ Add attributes like name, location, and road names
  • 📊 Configure the simulation in one of two ways:

🧪 Manual Configuration (for hobbyists / all users)

  • Choose variable parameters like:
    • 🚗 Traffic probabilities for each road
    • 🚦 Traffic light timing durations

📈 Data-Driven Configuration (for traffic departments)

  • Upload time-series traffic data
  • The system parses and uses this data to configure the simulation automatically

📉 Simulation Insights

After creating a simulation, users can:

  • 🔍 View detailed metrics and statistics
  • 📈 Analyze road-specific performance
  • 💾 Save and revisit simulations at any time

🤖 Optimization Feature

Users can improve the performance of any existing simulation with a single click:

  • 🧠 A machine learning algorithm will automatically analyze the simulation and generate optimized traffic light timings
  • 💾 The optimized configuration is saved and linked to the original simulation
  • 📊 Users are shown a side-by-side comparison of the original and optimized timings and metrics

📋 Formal User Stories

Login Screen

Login Form Functionality

  • Given I am on the login page, I should see a form with fields for username and password.
  • When I enter text in the username field, the input should update the username state.
  • When I enter text in the password field, the input should update the password state.
  • When I submit the form with both fields filled, the system should log the input values and redirect me to the dashboard page.
  • When I submit the form with either field empty, the system should display a console message indicating that all fields must be filled.

Traffic Light Indicator

  • Given I am on the login page, I should see a traffic light component with red, yellow, and green lights.
  • When the username field is empty, the red and yellow lights should appear inactive (dimmed with a neutral border).
  • When I enter text in the username field, the red and yellow lights should activate (bright with a glowing effect and distinct border).
  • When I enter text in the password field, the green light should activate (bright with a glowing effect and distinct border).
  • The traffic light should have a modern, visually appealing design with smooth transitions and shadow effects.

Forgot Password Modal

  • Given I am on the login page, I should see a "Forgot Password?" link.
  • When I click the "Forgot Password?" link, a modal should appear with an email input field and "Cancel" and "Send Reset Link" buttons.
  • When I enter an email and click "Send Reset Link," the system should log the email and close the modal.
  • When I click "Cancel," the modal should close without logging any data.
  • The modal should be styled consistently with the login page and appear centered with a semi-transparent background.

Navigation

  • Given I am on the login page, I should see a "Register Here" link.
  • When I click the "Register Here" link, I should be redirected to the signup page.
  • When I successfully submit the login form, I should be redirected to the dashboard page.

Visual and Accessibility Requirements

  • The login page should have a responsive design, adapting to mobile and desktop screens.
  • The page should include a logo and a welcome message ("Welcome to Swift Signals") at the top.
  • Form inputs should have accessible labels (e.g., using sr-only for screen readers).
  • The traffic light and form elements should use Tailwind CSS for consistent styling.
  • The page should use a light color scheme with a gradient background and shadow effects for a modern look.

Sign-Up Screen

Sign-Up Form Functionality

  • Given I am on the sign-up page, I should see a form with fields for username, email, and password.
  • When I enter text in the username field, the input should update the username state.
  • When I enter text in the email field, the input should update the email state.
  • When I enter text in the password field, the input should update the password state.
  • When I submit the form with all fields filled, the system should log the input values and redirect me to the login page.
  • When I submit the form with any field empty, the system should display a console message indicating that all fields must be filled.

Traffic Light Indicator

  • Given I am on the sign-up page, I should see a traffic light component with red, yellow, and green lights.
  • When the username field is empty, the red light should appear inactive (dimmed with a neutral border).
  • When I enter text in the username field, the red light should activate (bright with a glowing effect and distinct border).
  • When I enter text in the email field, the yellow light should activate (bright with a glowing effect and distinct border).
  • When I enter text in the password field, the green light should activate (bright with a glowing effect and distinct border).
  • The traffic light should have a modern, visually appealing design with smooth transitions and shadow effects.

Navigation

  • Given I am on the sign-up page, I should see a "Login here" link.
  • When I click the "Login here" link, I should be redirected to the login page.
  • When I successfully submit the sign-up form, I should be redirected to the login page.

Visual and Accessibility Requirements

  • The sign-up page should have a responsive design, adapting to mobile and desktop screens.
  • The page should include a logo and a welcome message ("Welcome to Swift Signals") at the top.
  • Form inputs should have accessible labels (e.g., using sr-only for screen readers).
  • The traffic light and form elements should use Tailwind CSS for consistent styling.
  • The page should use a light color scheme with a gradient background and shadow effects for a modern look.

Dashboard Screen

Summary Cards

  • Given I am on the dashboard page, I should see three summary cards displaying:
    • Total Intersections (e.g., "24") with a road icon.
    • Active Simulations (e.g., "8") with a play icon.
    • Optimization Runs (e.g., "156") with a chart line icon.
  • Each card should have a consistent design with Tailwind CSS styling, including icons in distinct colors (blue, green, purple) and a clean layout.

Quick Actions

  • Given I am on the dashboard page, I should see three quick action buttons:
    • "New Intersection" with a plus icon.
    • "Run Simulation" with a play icon.
    • "View Map" with a map icon.
  • Each button should have a distinct background color (indigo, green, purple) and hover effects.
  • Clicking the buttons should be clickable but currently log no action (placeholder functionality).
Recent Simulations Table
  • Given I am on the dashboard page, I should see a table listing recent simulations with columns for:
    • ID (e.g., "#1234").
    • Intersection (e.g., "Main St & 5th Ave").
    • Status (e.g., "Complete", "Running", "Failed").
    • Actions (e.g., "View Details" button).
  • The status should display with color-coded badges (green for Complete, yellow for Running, red for Failed).
  • The "View Details" button should be styled as a clickable link but currently log no action.

Traffic Volume Chart

  • Given I am on the dashboard page, I should see a line chart displaying traffic volume over time (e.g., 6 AM to 10 AM).
  • The chart should use Chart.js with a gradient fill (red-to-transparent), smooth line tension, and customized tooltips styled with Tailwind CSS colors.
  • The chart should be responsive, with no grid lines on the x-axis, light grid lines on the y-axis, and formatted tick labels.
  • The chart should clean up properly when the component unmounts to prevent memory leaks.

Top Intersections Section

  • Given I am on the dashboard page, I should see a section listing the top intersections by vehicle volume (e.g., "Main St & 5th Ave: 15,000 vehicles").
  • The section should include an "Avg Daily Volume" summary (e.g., "12,000 vehicles").
  • The data should be displayed in a clean, bordered list with Tailwind CSS styling.

Visual and Accessibility Requirements

  • The dashboard should include a Navbar at the top and a Footer at the bottom, consistent with the application's design.
  • The page should have a responsive layout, adapting to mobile and desktop screens using a grid system for larger screens.
  • The page should use a light background (gray-100) with dark mode support (gray-900).
  • All text, including headings, should be styled with Tailwind CSS for consistency and readability.
  • The chart and table should be accessible, with clear labels and color contrasts suitable for screen readers and visual clarity.

Intersections Page

Search Functionality

  • Given I am on the intersections page, I should see a search bar with a placeholder text "Search by Name or ID...".
  • When I type in the search bar, the list of intersections should dynamically filter to show only those matching the search query by name (case-insensitive) or ID.
  • The search bar should include a search icon (from Lucide React) positioned on the right side.
  • The search bar should be styled with Tailwind CSS, including a border, rounded edges, and a focus ring in red.

Intersection List

  • Given I am on the intersections page, I should see a list of intersection cards, each displaying:
    • ID (e.g., "1").
    • Name (e.g., "Main St & 1st Ave").
    • Location (e.g., "Pretoria CBD").
    • Lanes (e.g., "4-way, 2 lanes each").
  • Each card should be rendered using the IntersectionCard component and support three actions: Simulate, Edit, and Delete.
  • Clicking the Simulate, Edit, or Delete buttons should log a corresponding message to the console (e.g., "Simulate 1", "Edit 1", "Delete 1").
  • If no intersections match the search query, the list should display no cards.

Add Intersection Button

  • Given I am on the intersections page, I should see an "Add Intersection" button styled in red (bg-red-700, hover:bg-red-800).
  • Clicking the button should log "Add Intersection" to the console (placeholder functionality).
  • The button should be positioned to the right of the search bar in the top bar.

Visual and Accessibility Requirements

  • The intersections page should include a Navbar at the top, consistent with the application's design.
  • The page should have a responsive layout, adapting to mobile and desktop screens, with a maximum width of 6xl (Tailwind CSS) and padding.
  • The page should use a light background (gray-100) with a scrollable container for the intersection list.
  • The search bar should have an accessible placeholder and be usable with screen readers.
  • Intersection cards should be spaced vertically and styled with Tailwind CSS for consistency and readability.
  • The search icon should be clearly visible and properly aligned within the search bar.

Simulations Page

Simulation and Optimization Tables

  • Given I am on the simulations page, I should see two tables: one for "Recent Simulations" and one for "Recent Optimizations".
  • Each table should display columns for:
    • Simulation ID (e.g., "SIM001").
    • Intersection (e.g., "Main St & 1st Ave").
    • Avg Wait Time (e.g., "45.2").
    • Throughput (e.g., "1200").
    • Graph (bar chart comparing wait time and throughput).
    • Status (e.g., "Complete", "Running", "Failed").
    • Actions (View Results and Delete buttons).
  • The status should display with color-coded badges (green for Complete, yellow for Running, red for Failed).
  • The bar chart should use Chart.js with gradient fills (green for wait time, blue for throughput), no axis labels, and modern styling (rounded bars, tooltips).
  • Clicking "View Results" should trigger an alert with the simulation ID (e.g., "Viewing results for simulation SIM001").
  • Clicking "Delete" should trigger an alert with the simulation ID (e.g., "Deleting simulation SIM001").
  • Each table should support pagination with 4 rows per page, displaying "Prev", page numbers, and "Next" buttons styled with Tailwind CSS gradients.

Filtering by Intersection

  • Given I am on the simulations page, each table should have a dropdown to filter by intersection or "All Intersections".
  • Selecting an intersection should filter the table to show only simulations/optimizations for that intersection and reset the page to 0.
  • The dropdown should list all unique intersections from the respective table’s data, plus "All Intersections".

New Simulation/Optimization Modal

  • Given I am on the simulations page, I should see a "New Simulation" button for the simulations table.
  • Clicking "New Simulation" should open a modal titled "New Simulation" (or "New Optimization" for future functionality).
  • The modal should include:
    • A text input for "Simulation Name".
    • A textarea for "Simulation Description".
    • An intersection selection section with three tabs: List, Search, and Map.
  • List Tab: Displays a dropdown of available intersections (from both tables’ data). Selecting an intersection adds it to the selected intersections list.
  • Search Tab: Allows typing a location and clicking "Add" to include it in the selected intersections list.
  • Map Tab: Displays an interactive Leaflet map centered at [-26.2041, 28.0473] (South Africa) with zoom level 6. Clicking the map places a marker, logs coordinates, and adds them as an intersection to the selected list.
  • Selected intersections should appear as removable pills (with a cross button) styled with Tailwind CSS.
  • Clicking "Create" should validate that a name and at least one intersection are provided, log the data, clear the form, and navigate to /simulation-results with the data.
  • Clicking "Cancel" or the close button (cross) should close the modal without saving.
  • The modal should have a semi-transparent background, dark mode support, and Tailwind CSS styling.

Visual and Accessibility Requirements

  • The page should include a Navbar at the top and a Footer at the bottom, consistent with the application's design.
  • The page should have a responsive layout, using a two-column grid for medium and larger screens, and a single-column layout for mobile.
  • The page should use a light background (gray-100) with dark mode support (gray-900).
  • Tables, inputs, and buttons should be styled with Tailwind CSS for consistency and readability.
  • The map should use OpenStreetMap tiles with proper attribution.
  • All inputs and interactive elements (dropdowns, buttons, map) should be accessible, with clear labels and sufficient contrast for screen readers and visual clarity.
  • Font Awesome icons (eye for View, trash for Delete) should be used in the table action buttons.

Simulation Results Page

Simulation Data Display

  • Given I am on the simulation results page, I should see the simulation's name, description, and intersections passed from the previous page via react-router-dom state.
  • The simulation name should be displayed as a large, bold heading with a teal-to-emerald gradient.
  • The description should be a paragraph in gray text.
  • Intersections should appear as clickable pills with a teal border and hover effects, styled using Tailwind CSS.
  • If no simulation data is available (e.g., no state passed), a "Loading..." message should display in the center.

Simulation Visualization Section

  • Given I am on the simulation results page, I should see a "Simulation Visualization" section with:
    • A bar chart displaying speed and density parameters (default: speed=50, density=30) using Chart.js.
    • The chart should have green bars (#34D399, #10B981), no legend, and customized tooltips with a dark background.
    • Axes should display "Parameter" (x) and "Value" (y, 0-100 range) with light grid lines and bold labels.
    • The section should include input fields for adjusting speed and density (number inputs, 0-100 range).
    • Input fields should be styled with Tailwind CSS, using a gray background and teal focus ring.
    • A "Run" button should toggle a "Running..." state for 2 seconds when clicked, disabling itself during this period.
    • An "Optimize" button should adjust optimized parameters (increase speed by 20 up to 100, decrease density by 10 down to 0).
    • Clicking the chart should open a full-screen modal displaying the same chart with a title ("Simulation Visualization").

Optimized Visualization Section

  • Given I am on the simulation results page, I should see an "Optimized Visualization" section with:
    • A bar chart displaying optimized speed and density parameters (default: speed=70, density=20) using Chart.js.
    • The chart should have blue bars (#3B82F6, #2563EB), no legend, and customized tooltips with a dark background.
    • Axes should match the simulation chart's configuration.
    • The section should include input fields for adjusting optimized speed and density (number inputs, 0-100 range).
    • Input fields should match the simulation section’s styling.
    • A "Run" button should toggle a "Running..." state for 2 seconds when clicked, disabling itself during this period.
    • Clicking the chart should open a full-screen modal displaying the same chart with a title ("Optimized Visualization").

Full-Screen Chart Modal

  • Given I click a chart in either visualization section, a full-screen modal should appear with:
    • The selected chart (simulation or optimized) rendered at full size using Chart.js.
    • A title matching the chart type ("Simulation Visualization" or "Optimized Visualization").
    • A close button (cross) in the top-right corner to exit the modal.
    • The modal should have a semi-transparent black background and be centered with a maximum width of 7xl.
    • Charts should clean up properly when the modal closes to prevent memory leaks.

Visual and Accessibility Requirements

  • The page should include a Navbar at the top and a dynamic Footer at the bottom, consistent with the application’s design.
  • The page should have a responsive layout, using a two-column grid for medium and larger screens and a single-column layout for mobile.
  • The page should use a dark gradient background (gray-900 to black) with light text for readability.
  • Charts, inputs, and buttons should be styled with Tailwind CSS, including gradients, shadows, and hover effects.
  • Input fields should have accessible labels and be constrained to valid ranges (0-100).
  • All interactive elements (buttons, charts, inputs) should have sufficient contrast and be usable with screen readers.

Users Page

Users Table Display

  • Given I am on the users page, I should see a table displaying user data with columns for:
    • ID (e.g., "1").
    • Name (e.g., "John Doe").
    • Role (e.g., "Admin", "Engineer", "Viewer").
    • Last Login (e.g., "2025-05-13 09:00").
  • The table should be rendered using the UsersTable component, passing the current page’s user data and handlers for Edit and Delete actions.
  • Clicking the Edit button for a user should log "Edit user [ID]" to the console.
  • Clicking the Delete button for a user should log "Delete user [ID]" to the console.

Pagination

  • Given I am on the users page, I should see pagination controls below the table, including:
    • A "Previous" button with a left arrow icon, disabled on the first page.
    • Numbered page buttons, showing up to 5 pages (first, last, and up to 3 around the current page).
    • An ellipsis ("...") for skipped page numbers when there are more than 5 pages.
    • A "Next" button with a right arrow icon, disabled on the last page.
    • Clicking a page number should display the corresponding user data slice (9 or 7 rows per page, depending on screen size).
    • Clicking "Previous" or "Next" should navigate to the adjacent page, updating the table data.
    • Pagination buttons should be styled with Tailwind CSS, with the active page highlighted in blue and hover effects on others.

Responsive Row Adjustments

  • Given I am on the users page, the table should display 9 rows per page by default.
  • When the screen size is 1400px or smaller and 800px or shorter, the table should display 7 rows per page, resetting to the first page.
  • The row adjustment should occur dynamically when the window size changes, using a media query listener.
  • The total number of pages should update automatically based on the number of users and rows per page.

Visual and Accessibility Requirements

  • The page should include a Navbar at the top, consistent with the application’s design.
  • The page should have a responsive layout, with a maximum width of 6xl (Tailwind CSS) and padding for content.
  • The page should use a light background (gray-100) for a clean appearance.
  • The table and pagination controls should be styled with Tailwind CSS for consistency and readability.
  • Pagination buttons should have accessible labels (e.g., "Previous page", "Next page") and use SVG icons for arrows.
  • The table should be accessible, with proper semantic structure and support for screen readers (handled by the UsersTable component).

Authentication

  • As a user,
    I want to register, log in, and manage my account,
    so that I can use the system securely and privately.

  • As a user,
    I want to reset my password if I forget it,
    so that I can regain access to my account.

Simulation Creation

  • As a user,
    I want to create a new simulation with basic intersection details,
    so that I can model traffic behavior.

  • As a user,
    I want to manually configure traffic flow probabilities and light timings,
    so that I can experiment with different traffic patterns.

  • As a traffic department user,
    I want to upload real-world traffic data,
    so that the system can create simulations based on actual conditions.

Simulation Insights

  • As a user,
    I want to view performance metrics for each simulation,
    so that I can understand and evaluate the traffic behavior.

Optimization

  • As a user,
    I want to optimize my simulation's timing,
    so that I can observe what timing's best suit my simulation

  • As a user,
    I want to compare the original and optimized configurations,
    so that I can see how the optimization has improved traffic flow.