# krishthakur248/quickpull architecture

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

- Interactive diagram: https://gitdiagram.com/krishthakur248/quickpull
- Repository: https://github.com/krishthakur248/quickpull

## Overview

#### Purpose and Entry Points
This repository implements a carpooling application with browser-based rider/driver screens and a separate Node.js backend. Primary UI entry points are `index.html`, `Dashboard-Connected.html`, and `AddRide-Connected.html`. The backend starts from `car-pulling-backend/src/server.js`.

#### Frontend Application Layer
The frontend is a static HTML/JavaScript client rather than a bundled web application. It manages authentication, API access, trip operations, matching, messaging, and notifications through shared service scripts:
- `api-client.js`
- `auth-service.js`
- `trip-service.js`
- `matchingService.js`
- `message-service.js`
- `notification-manager.js`

Connected pages likely invoke these services to render dashboards, create rides, find rides, and communicate with matched users.

#### Backend HTTP/API Boundary
The backend follows a conventional Express-style separation of server, routes, controllers, middleware, and models. `car-pulling-backend/src/server.js` accepts HTTP requests and delegates them through route modules:
- `car-pulling-backend/src/routes/auth.routes.js`
- `car-pulling-backend/src/routes/trip.routes.js`
- `car-pulling-backend/src/routes/message.routes.js`
- `car-pulling-backend/src/routes/user.routes.js`

Controllers implement the API operations and form the boundary between request handling, persistence, and matching logic.

#### Identity and Authorization
Authentication is handled by controller, route, and middleware layers:
- `car-pulling-backend/src/controllers/auth.controller.js`
- `car-pulling-backend/src/routes/auth.routes.js`
- `car-pulling-backend/src/middleware/auth.js`

The browser-side counterpart is `auth-service.js`. Protected trip, user, and messaging operations should pass through the authentication middleware before reaching controllers.

#### Core Domain and Persistence
The durable application entities are users, trips, and messages:
- `car-pulling-backend/src/models/User.js`
- `car-pulling-backend/src/models/Trip.js`
- `car-pulling-backend/src/models/Message.js`

Database initialization/configuration is isolated in `car-pulling-backend/src/config/database.js`. Trip lifecycle operations—including publishing, finding, accepting, completing, and location-related updates—are centered in `car-pulling-backend/src/controllers/trip.controller.js`.

#### Route Matching Pipeline
Trip discovery and compatibility evaluation are a distinct backend capability, not only a frontend filter. Matching utilities are:
- `car-pulling-backend/src/utils/matchingEngine.js`
- `car-pulling-backend/src/utils/advancedRouteMatching.js`
- `car-pulling-backend/src/controllers/trip.controller.js`

The expected flow is: client submits or queries trips; the trip controller loads relevant trip data; matching utilities evaluate route compatibility; matching results return through trip APIs to frontend services such as `matchingService.js`. The repository’s OSRM-focused documentation and test files indicate routing/mapping integration is an important external-service boundary.

#### Messaging and Realtime/Location Concerns
Messaging is exposed as its own API/domain path:
- `car-pulling-backend/src/controllers/message.controller.js`
- `car-pulling-backend/src/routes/message.routes.js`
- `message-service.js`

Location tracking and active-trip behavior appear architecturally significant from the dedicated integration/debugging materials and trip-focused client code. Relevant validation harnesses include `Testing/verify-location-tracking.js` and `Testing/debug-trip-completion.js`; production logic remains primarily under the trip controller and trip model.

#### Runtime and Integration Shape
The system consists of a static browser frontend plus a Node.js backend with package-managed dependencies in `car-pulling-backend/package.json`. It relies on a configured database via `car-pulling-backend/src/config/database.js` and has route-matching integration points associated with OSRM, evidenced by `Testing/test-osrm.js` and `car-pulling-backend/src/utils/advancedRouteMatching.js`.

Main entry points: [`api-client.js`](https://github.com/krishthakur248/quickpull/blob/master/api-client.js) (API client), [`Dashboard-Connected.html`](https://github.com/krishthakur248/quickpull/blob/master/Dashboard-Connected.html) (Connected dashboard), [`car-pulling-backend/src/middleware/auth.js`](https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/middleware/auth.js) (Auth middleware), [`car-pulling-backend/src/controllers/trip.controller.js`](https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/controllers/trip.controller.js) (Trip controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser client"]
  node_landing["Landing page<br/>HTML entry<br/>[index.html]"]
  node_dashboard["Connected dashboard<br/>HTML entry"]
  node_add_ride["Add ride page<br/>HTML entry"]
  node_api_client["API client<br/>browser HTTP service<br/>[api-client.js]"]
  node_auth_client["Auth service<br/>[auth-service.js]"]
  node_trip_client["Trip service<br/>[trip-service.js]"]
  node_matching_client["Matching service<br/>[matchingService.js]"]
  node_message_client["Message service<br/>browser messaging service<br/>[message-service.js]"]
  node_notifications["Notification manager<br/>browser notification service"]
end

subgraph group_api["Node.js API"]
  node_server{{"Express server<br/>Node.js entry point<br/>[server.js]"}}
  node_routes["API routes<br/>route modules"]
  node_auth_middleware["Auth middleware<br/>authorization middleware<br/>[auth.js]"]
  node_auth_controller["Auth controller<br/>[auth.controller.js]"]
  node_trip_controller["Trip controller<br/>[trip.controller.js]"]
  node_message_controller["Message controller"]
  node_matching_engine["Route matching<br/>matching utilities"]
end

subgraph group_data["Persistence"]
  node_database_config[("Database connection<br/>database configuration<br/>[database.js]")]
  node_entities[("Users, trips, messages<br/>data models")]
end

subgraph group_external["External integration"]
  node_osrm{{"OSRM routing<br/>routing service"}}
end

node_landing -->|"uses"| node_api_client
node_dashboard -->|"authenticates"| node_auth_client
node_dashboard -->|"manages trips"| node_trip_client
node_dashboard -->|"finds matches"| node_matching_client
node_dashboard -->|"messages"| node_message_client
node_dashboard -->|"notifies"| node_notifications
node_add_ride -->|"publishes ride"| node_trip_client
node_auth_client -->|"calls"| node_api_client
node_trip_client -->|"calls"| node_api_client
node_matching_client -->|"calls"| node_api_client
node_message_client -->|"calls"| node_api_client
node_api_client -->|"HTTP"| node_server
node_server -->|"mounts"| node_routes
node_routes -->|"protects operations"| node_auth_middleware
node_routes -->|"auth endpoints"| node_auth_controller
node_auth_middleware -->|"authorizes"| node_trip_controller
node_auth_middleware -->|"authorizes"| node_message_controller
node_trip_controller -->|"evaluates compatibility"| node_matching_engine
node_matching_engine -->|"routing queries"| node_osrm
node_auth_controller -->|"reads and writes users"| node_entities
node_trip_controller -->|"reads and writes trips"| node_entities
node_message_controller -->|"reads and writes messages"| node_entities
node_entities -->|"connects through"| node_database_config

click node_landing "https://github.com/krishthakur248/quickpull/blob/master/index.html"
click node_dashboard "https://github.com/krishthakur248/quickpull/blob/master/Dashboard-Connected.html"
click node_add_ride "https://github.com/krishthakur248/quickpull/blob/master/AddRide-Connected.html"
click node_api_client "https://github.com/krishthakur248/quickpull/blob/master/api-client.js"
click node_auth_client "https://github.com/krishthakur248/quickpull/blob/master/auth-service.js"
click node_trip_client "https://github.com/krishthakur248/quickpull/blob/master/trip-service.js"
click node_matching_client "https://github.com/krishthakur248/quickpull/blob/master/matchingService.js"
click node_message_client "https://github.com/krishthakur248/quickpull/blob/master/message-service.js"
click node_notifications "https://github.com/krishthakur248/quickpull/blob/master/notification-manager.js"
click node_server "https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/server.js"
click node_auth_middleware "https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/middleware/auth.js"
click node_auth_controller "https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/controllers/auth.controller.js"
click node_trip_controller "https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/controllers/trip.controller.js"
click node_message_controller "https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/controllers/message.controller.js"
click node_matching_engine "https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/utils/advancedRouteMatching.js"
click node_database_config "https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/config/database.js"

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_landing,node_dashboard,node_add_ride,node_api_client,node_auth_client,node_trip_client,node_matching_client,node_message_client,node_notifications toneBlue
class node_server,node_routes,node_auth_middleware,node_auth_controller,node_trip_controller,node_message_controller,node_matching_engine toneAmber
class node_database_config,node_entities toneMint
class node_osrm toneRose
```

## Components

### Browser client

Static HTML and shared JavaScript services.

- [Landing page](https://github.com/krishthakur248/quickpull/blob/master/index.html): HTML entry · `index.html`
- [Connected dashboard](https://github.com/krishthakur248/quickpull/blob/master/Dashboard-Connected.html): HTML entry · Rider and driver trip experience. · `Dashboard-Connected.html`
- [Add ride page](https://github.com/krishthakur248/quickpull/blob/master/AddRide-Connected.html): HTML entry · `AddRide-Connected.html`
- [API client](https://github.com/krishthakur248/quickpull/blob/master/api-client.js): browser HTTP service · `api-client.js`
- [Auth service](https://github.com/krishthakur248/quickpull/blob/master/auth-service.js): browser auth service · `auth-service.js`
- [Trip service](https://github.com/krishthakur248/quickpull/blob/master/trip-service.js): browser trip service · `trip-service.js`
- [Matching service](https://github.com/krishthakur248/quickpull/blob/master/matchingService.js): browser matching service · `matchingService.js`
- [Message service](https://github.com/krishthakur248/quickpull/blob/master/message-service.js): browser messaging service · `message-service.js`
- [Notification manager](https://github.com/krishthakur248/quickpull/blob/master/notification-manager.js): browser notification service · `notification-manager.js`

### Node.js API

Express server request and domain layers.

- [Express server](https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/server.js): Node.js entry point · `car-pulling-backend/src/server.js`
- **API routes**: route modules · Auth, trip, message, and user endpoints.
- [Auth middleware](https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/middleware/auth.js): authorization middleware · `car-pulling-backend/src/middleware/auth.js`
- [Auth controller](https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/controllers/auth.controller.js): controller · `car-pulling-backend/src/controllers/auth.controller.js`
- [Trip controller](https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/controllers/trip.controller.js): controller · Owns trip lifecycle and location-related operations. · `car-pulling-backend/src/controllers/trip.controller.js`
- [Message controller](https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/controllers/message.controller.js): controller · `car-pulling-backend/src/controllers/message.controller.js`
- [Route matching](https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/utils/advancedRouteMatching.js): matching utilities · Evaluates trip and route compatibility. · `car-pulling-backend/src/utils/advancedRouteMatching.js`

### Persistence

Database-backed durable entities.

- [Database connection](https://github.com/krishthakur248/quickpull/blob/master/car-pulling-backend/src/config/database.js): database configuration · `car-pulling-backend/src/config/database.js`
- **Users, trips, messages**: data models · Durable application entities.

### External integration

- **OSRM routing**: routing service · Route-matching integration boundary.

## Connections

- Landing page → API client: uses
- Connected dashboard → Auth service: authenticates
- Connected dashboard → Trip service: manages trips
- Connected dashboard → Matching service: finds matches
- Connected dashboard → Message service: messages
- Connected dashboard → Notification manager: notifies
- Add ride page → Trip service: publishes ride
- Auth service → API client: calls
- Trip service → API client: calls
- Matching service → API client: calls
- Message service → API client: calls
- API client → Express server: HTTP
- Express server → API routes: mounts
- API routes → Auth middleware: protects operations
- API routes → Auth controller: auth endpoints
- Auth middleware → Trip controller: authorizes
- Auth middleware → Message controller: authorizes
- Trip controller → Route matching: evaluates compatibility
- Route matching → OSRM routing: routing queries
- Auth controller → Users, trips, messages: reads and writes users
- Trip controller → Users, trips, messages: reads and writes trips
- Message controller → Users, trips, messages: reads and writes messages
- Users, trips, messages → Database connection: connects through