# alokinfilon/trackmate architecture

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

- Interactive diagram: https://gitdiagram.com/alokinfilon/trackmate
- Repository: https://github.com/alokinfilon/trackmate

## Overview

#### Purpose and Entry Point
This is a Node.js API backend for travel-oriented users: authentication, trips, locations, galleries, notifications, and supporting content such as FAQs, reviews, and travel preferences. The process starts at `index.js`, with application-level request handling in `controllers/appController.js`.

#### HTTP API Surface
Feature routes partition the public API by domain:
- Authentication: `routes/auth.js`, `controllers/auth.js`
- Trips: `routes/trip.routes.js`, `controllers/trip.controller.js`
- Gallery/media: `routes/gallery.routes.js`, `controllers/gallery.controller.js`
- Locations: `routes/locationRoutes.js`, `controllers/location.js`
- Notifications: `routes/notification.routes.js`, `controllers/notification.controller.js`

`routes/apiRoutes.js` is the likely route aggregation boundary. Swagger definitions under `docs/` and `swagger/swagger.js` document the API contract.

#### Identity and Request Security
Authentication is handled through controllers and shared middleware. `middleware/auth.middleware.js` protects authenticated endpoints, while `middleware/passport.js` configures Passport-based identity handling. Refresh-token persistence is represented by `models/refreshToken.js`; user records are defined in `models/user.js`.

The flow is: auth route → auth controller → user/token models → protected feature routes through auth middleware.

#### Domain Persistence Layer
Mongo-style model definitions appear to be centralized in `models/index.js`, with separate records for primary entities:
- Trips and collections: `models/trip.model.js`, `models/collection.model.js`, `models/collectionShare.js`
- Gallery assets: `models/gallery.model.js`
- Geographic content: `models/location.js`
- User-facing content and preferences: `models/faq.js`, `models/travelPreference.js`, `models/review.js`
- Device delivery state: `models/deviceToken.js`, `models/notification.js`

Database initialization and seed loading are separated in `database/connection.js` and `database/seed.js`.

#### Location and Travel Data Boundary
Location behavior has a repository layer in `repository/location.repo.js`, distinct from its controller in `controllers/location.js`. This is the clearest data-access abstraction in the repository and likely mediates database-backed location lookup or aggregation. Static/bootstrap travel content is also present under `data/location_data.json` and `data/travel_preference_data.json`.

#### Media and Sharing Flow
Gallery endpoints coordinate gallery records with external media storage through `utils/cloudinary.js`. Gallery-specific transformation or validation logic is isolated in `utils/gallery.helper.js`. Collections and collection shares (`models/collection.model.js`, `models/collectionShare.js`) indicate that trip/gallery content can be grouped and shared independently of core trip ownership.

#### Notifications and External Delivery
Notification request handling resides in `controllers/notification.controller.js`; persisted notification and device-token state are in `models/notification.js` and `models/deviceToken.js`. `utils/firebase.js` and `utils/notification.service.js` form the external push-notification boundary, likely sending to registered client devices rather than directly coupling controllers to Firebase.

#### Cross-Cutting Failure Handling
Request validation and failure normalization are centralized in `middleware/validator.js`, `middleware/errorHandler.js`, and `middleware/notFound.js`. These form the API boundary around feature controllers: validate input before domain handling, return standardized errors for thrown failures, and handle unmatched routes consistently.

Main entry points: [`routes/apiRoutes.js`](https://github.com/alokinfilon/trackmate/blob/main/routes/apiRoutes.js) (API route aggregator), [`database/connection.js`](https://github.com/alokinfilon/trackmate/blob/main/database/connection.js) (Mongo database setup), [`middleware/auth.middleware.js`](https://github.com/alokinfilon/trackmate/blob/main/middleware/auth.middleware.js) (Authenticated-route guard), [`routes/gallery.routes.js`](https://github.com/alokinfilon/trackmate/blob/main/routes/gallery.routes.js) (Gallery API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_entry["Node entry point<br/>runtime bootstrap<br/>[index.js]"]
  node_app["Application handler<br/>request composition<br/>[appController.js]"]
  node_api_routes["API route aggregator<br/>route boundary<br/>[apiRoutes.js]"]
  node_trip_api["Trips API<br/>routes + controller<br/>[trip.routes.js]"]
  node_gallery_api["Gallery API<br/>routes + controller<br/>[gallery.routes.js]"]
  node_location_api["Locations API<br/>routes + controller<br/>[locationRoutes.js]"]
  node_notification_api["Notifications API<br/>routes + controller"]
  node_request_guard["Validation &amp; error handling<br/>middleware pipeline<br/>[validator.js]"]
  node_api_docs["Swagger API contract<br/>API documentation<br/>[swagger.js]"]
end

subgraph group_identity["Identity &amp; Security"]
  node_auth_api["Authentication API<br/>routes + controller<br/>[auth.js]"]
  node_passport["Passport identity<br/>identity configuration<br/>[passport.js]"]
  node_auth_guard["Authenticated-route guard<br/>auth middleware<br/>[auth.middleware.js]"]
  node_identity_records[("Users &amp; refresh tokens<br/>identity models<br/>[user.js]")]
end

subgraph group_domain["Domain &amp; Persistence"]
  node_trip_records[("Trips &amp; shared collections<br/>domain models<br/>[trip.model.js]")]
  node_gallery_records[("Gallery records<br/>media model<br/>[gallery.model.js]")]
  node_location_repository["Location repository<br/>data-access layer<br/>[location.repo.js]"]
  node_location_records[("Location content<br/>location model<br/>[location.js]")]
  node_content_records[("Preferences &amp; reviews<br/>supporting content models")]
  node_notification_records[("Notifications &amp; devices<br/>delivery-state models<br/>[notification.js]")]
  node_database[("Mongo database setup<br/>database connection<br/>[connection.js]")]
end

subgraph group_integrations["External Delivery"]
  node_cloudinary{{"Cloudinary media storage<br/>media integration<br/>[cloudinary.js]"}}
  node_push_service{{"Push notification service<br/>Firebase delivery adapter"}}
end

node_entry -->|"starts"| node_app
node_app -->|"mounts"| node_api_routes
node_app -->|"applies"| node_request_guard
node_api_routes -->|"routes"| node_auth_api
node_api_routes -->|"routes"| node_trip_api
node_api_routes -->|"routes"| node_gallery_api
node_api_routes -->|"routes"| node_location_api
node_api_routes -->|"routes"| node_notification_api
node_auth_api -->|"reads and writes"| node_identity_records
node_auth_api -->|"uses"| node_passport
node_auth_guard -->|"verifies identity with"| node_passport
node_auth_guard -.->|"protects"| node_trip_api
node_auth_guard -.->|"protects"| node_gallery_api
node_auth_guard -.->|"protects"| node_notification_api
node_trip_api -->|"manages"| node_trip_records
node_gallery_api -->|"manages"| node_gallery_records
node_gallery_api -->|"stores media through"| node_cloudinary
node_location_api -->|"queries through"| node_location_repository
node_location_repository -->|"accesses"| node_location_records
node_notification_api -->|"persists state"| node_notification_records
node_notification_api -->|"sends through"| node_push_service
node_trip_records -.->|"persists via"| node_database
node_gallery_records -.->|"persists via"| node_database
node_location_records -.->|"persists via"| node_database
node_notification_records -.->|"persists via"| node_database
node_identity_records -.->|"persists via"| node_database
node_content_records -.->|"persists via"| node_database
node_api_docs -.->|"documents"| node_api_routes

click node_entry "https://github.com/alokinfilon/trackmate/blob/main/index.js"
click node_app "https://github.com/alokinfilon/trackmate/blob/main/controllers/appController.js"
click node_api_routes "https://github.com/alokinfilon/trackmate/blob/main/routes/apiRoutes.js"
click node_auth_api "https://github.com/alokinfilon/trackmate/blob/main/routes/auth.js"
click node_trip_api "https://github.com/alokinfilon/trackmate/blob/main/routes/trip.routes.js"
click node_gallery_api "https://github.com/alokinfilon/trackmate/blob/main/routes/gallery.routes.js"
click node_location_api "https://github.com/alokinfilon/trackmate/blob/main/routes/locationRoutes.js"
click node_notification_api "https://github.com/alokinfilon/trackmate/blob/main/routes/notification.routes.js"
click node_request_guard "https://github.com/alokinfilon/trackmate/blob/main/middleware/validator.js"
click node_passport "https://github.com/alokinfilon/trackmate/blob/main/middleware/passport.js"
click node_auth_guard "https://github.com/alokinfilon/trackmate/blob/main/middleware/auth.middleware.js"
click node_identity_records "https://github.com/alokinfilon/trackmate/blob/main/models/user.js"
click node_trip_records "https://github.com/alokinfilon/trackmate/blob/main/models/trip.model.js"
click node_gallery_records "https://github.com/alokinfilon/trackmate/blob/main/models/gallery.model.js"
click node_location_repository "https://github.com/alokinfilon/trackmate/blob/main/repository/location.repo.js"
click node_location_records "https://github.com/alokinfilon/trackmate/blob/main/models/location.js"
click node_content_records "https://github.com/alokinfilon/trackmate/blob/main/models/travelPreference.js"
click node_notification_records "https://github.com/alokinfilon/trackmate/blob/main/models/notification.js"
click node_database "https://github.com/alokinfilon/trackmate/blob/main/database/connection.js"
click node_cloudinary "https://github.com/alokinfilon/trackmate/blob/main/utils/cloudinary.js"
click node_push_service "https://github.com/alokinfilon/trackmate/blob/main/utils/notification.service.js"
click node_api_docs "https://github.com/alokinfilon/trackmate/blob/main/swagger/swagger.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_entry,node_app,node_api_routes,node_trip_api,node_gallery_api,node_location_api,node_notification_api,node_request_guard,node_api_docs toneBlue
class node_auth_api,node_passport,node_auth_guard,node_identity_records toneAmber
class node_trip_records,node_gallery_records,node_location_repository,node_location_records,node_content_records,node_notification_records,node_database toneMint
class node_cloudinary,node_push_service toneRose
```

## Components

### HTTP API

- [Node entry point](https://github.com/alokinfilon/trackmate/blob/main/index.js): runtime bootstrap · `index.js`
- [Application handler](https://github.com/alokinfilon/trackmate/blob/main/controllers/appController.js): request composition · `controllers/appController.js`
- [API route aggregator](https://github.com/alokinfilon/trackmate/blob/main/routes/apiRoutes.js): route boundary · `routes/apiRoutes.js`
- [Trips API](https://github.com/alokinfilon/trackmate/blob/main/routes/trip.routes.js): routes + controller · `routes/trip.routes.js`
- [Gallery API](https://github.com/alokinfilon/trackmate/blob/main/routes/gallery.routes.js): routes + controller · `routes/gallery.routes.js`
- [Locations API](https://github.com/alokinfilon/trackmate/blob/main/routes/locationRoutes.js): routes + controller · `routes/locationRoutes.js`
- [Notifications API](https://github.com/alokinfilon/trackmate/blob/main/routes/notification.routes.js): routes + controller · `routes/notification.routes.js`
- [Validation & error handling](https://github.com/alokinfilon/trackmate/blob/main/middleware/validator.js): middleware pipeline · Validates requests and normalizes failures or unmatched routes. · `middleware/validator.js`
- [Swagger API contract](https://github.com/alokinfilon/trackmate/blob/main/swagger/swagger.js): API documentation · `swagger/swagger.js`

### Identity & Security

- [Authentication API](https://github.com/alokinfilon/trackmate/blob/main/routes/auth.js): routes + controller · `routes/auth.js`
- [Passport identity](https://github.com/alokinfilon/trackmate/blob/main/middleware/passport.js): identity configuration · `middleware/passport.js`
- [Authenticated-route guard](https://github.com/alokinfilon/trackmate/blob/main/middleware/auth.middleware.js): auth middleware · `middleware/auth.middleware.js`
- [Users & refresh tokens](https://github.com/alokinfilon/trackmate/blob/main/models/user.js): identity models · `models/user.js`

### Domain & Persistence

- [Trips & shared collections](https://github.com/alokinfilon/trackmate/blob/main/models/trip.model.js): domain models · `models/trip.model.js`
- [Gallery records](https://github.com/alokinfilon/trackmate/blob/main/models/gallery.model.js): media model · `models/gallery.model.js`
- [Location repository](https://github.com/alokinfilon/trackmate/blob/main/repository/location.repo.js): data-access layer · Mediates location lookup and aggregation. · `repository/location.repo.js`
- [Location content](https://github.com/alokinfilon/trackmate/blob/main/models/location.js): location model · `models/location.js`
- [Preferences & reviews](https://github.com/alokinfilon/trackmate/blob/main/models/travelPreference.js): supporting content models · `models/travelPreference.js`
- [Notifications & devices](https://github.com/alokinfilon/trackmate/blob/main/models/notification.js): delivery-state models · `models/notification.js`
- [Mongo database setup](https://github.com/alokinfilon/trackmate/blob/main/database/connection.js): database connection · `database/connection.js`

### External Delivery

- [Cloudinary media storage](https://github.com/alokinfilon/trackmate/blob/main/utils/cloudinary.js): media integration · `utils/cloudinary.js`
- [Push notification service](https://github.com/alokinfilon/trackmate/blob/main/utils/notification.service.js): Firebase delivery adapter · `utils/notification.service.js`

## Connections

- Node entry point → Application handler: starts
- Application handler → API route aggregator: mounts
- Application handler → Validation & error handling: applies
- API route aggregator → Authentication API: routes
- API route aggregator → Trips API: routes
- API route aggregator → Gallery API: routes
- API route aggregator → Locations API: routes
- API route aggregator → Notifications API: routes
- Authentication API → Users & refresh tokens: reads and writes
- Authentication API → Passport identity: uses
- Authenticated-route guard → Passport identity: verifies identity with
- Authenticated-route guard → Trips API: protects
- Authenticated-route guard → Gallery API: protects
- Authenticated-route guard → Notifications API: protects
- Trips API → Trips & shared collections: manages
- Gallery API → Gallery records: manages
- Gallery API → Cloudinary media storage: stores media through
- Locations API → Location repository: queries through
- Location repository → Location content: accesses
- Notifications API → Notifications & devices: persists state
- Notifications API → Push notification service: sends through
- Trips & shared collections → Mongo database setup: persists via
- Gallery records → Mongo database setup: persists via
- Location content → Mongo database setup: persists via
- Notifications & devices → Mongo database setup: persists via
- Users & refresh tokens → Mongo database setup: persists via
- Preferences & reviews → Mongo database setup: persists via
- Swagger API contract → API route aggregator: documents