# raiyashu2004/nomadix architecture

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

- Interactive diagram: https://gitdiagram.com/raiyashu2004/nomadix
- Repository: https://github.com/raiyashu2004/nomadix

## Overview

1. **System shape**
   - NOMADIX is a split frontend/backend app with a small auxiliary Python service.
   - The main product loop is: authenticate → create/join group → collect survey inputs → generate destination recommendations → vote in real time.

2. **Backend is the system of record**
   - The `BACKEND/` service is a Node.js + Express API backed by MongoDB via Mongoose.
   - It owns all persistent domain state: users, groups, surveys, recommendations, votes, chat messages, itineraries, memories, parties, availability, and bills.

3. **Core domain boundaries**
   - The code is organized by feature: `controllers/`, `models/`, and `routes/` are aligned around those business areas.
   - The consensus MVP centers on `auth`, `groups`, `survey`, `recommendations`, and `votes`; the other entities appear to support broader trip coordination features.

4. **Consensus engine**
   - Destination recommendations are generated from local seed data in `src/data/destinations.json`.
   - A deterministic algorithm in `src/utils/consensus.js` computes a group profile from survey responses and scores destinations by tag match, producing the top 3 recommendations without any external API.

5. **Recommendation data flow**
   - Members submit survey answers to the backend.
   - The leader triggers generation, which reads survey state and destination seed data, writes recommendation records, and exposes them through the API.
   - Voting then updates vote counts against those generated options.

6. **Real-time synchronization**
   - Socket.io is used to keep group activity in sync across clients.
   - The socket layer has explicit auth handling (`socketAuth.js`) and room membership per group (`join_group_room`), with server broadcasts for survey submission, recommendation generation, and vote updates.
   - `connectedUsers.js` suggests user presence/session tracking for live collaboration.

7. **Authentication and access control**
   - JWT-based auth is used across the backend, with token generation in `src/utils/generateToken.js` and request protection in `src/middlewares/authMiddleware.js`.
   - The API is mostly private: authenticated users can access groups and trip data, while register/login are the main public entry points.

8. **Frontend is a thin interactive client**
   - The `frontend/` app is a React + TypeScript SPA built with Vite and Tailwind.
   - It consumes the backend via Axios wrappers in `src/api/` and keeps client state in Zustand stores under `src/store/`.

9. **Frontend feature composition**
   - Pages are organized around user journeys: login/register, dashboard, consensus, and party views.
   - Reusable UI widgets cover the main collaboration surfaces: chat, itinerary timeline/map, bill split, shared gallery, and voting progress.

10. **Frontend realtime integration**
   - `src/socket.ts` is the client-side socket singleton.
   - UI state changes are driven by both REST responses and live socket events, so the app stays consistent when other group members submit surveys or cast votes.

11. **Supporting trip-planning modules**
   - The backend includes endpoints and models for chat, itinerary, memories, parties, availability, and bills, indicating the platform is designed beyond consensus alone.
   - These modules are present as separate domain slices, but the current README and UI suggest consensus is the primary shipped workflow.

12. **Auxiliary Python service**
   - `bill-scanner/` is a separate Python/FastAPI-style OCR service area with its own dependencies.
   - It is part of the repository but appears outside the MVP consensus flow, likely intended for receipt scanning or expense automation later.

13. **Infrastructure and local runtime**
   - The backend expects MongoDB plus JWT secrets in environment variables.
   - The frontend dev server proxies `/api/*` to the backend, so the browser talks to one origin in development while the backend handles both REST and Socket.io traffic.

Main entry points: [`BACKEND/src/app.js`](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/app.js) (API app), [`BACKEND/src/models`](https://github.com/raiyashu2004/nomadix/tree/main/BACKEND/src/models) (Mongo models), [`BACKEND/src/sockets/journeySocket.js`](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/sockets/journeySocket.js) (Realtime sync), [`BACKEND/src/controllers/recommendationController.js`](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/controllers/recommendationController.js) (Recommendations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_server["Server<br/>Express bootstrap<br/>[server.js]"]
  node_backend_app["API app<br/>Express app<br/>[app.js]"]
  node_backend_auth["Auth<br/>JWT access control<br/>[authController.js]"]
  node_backend_groups["Groups<br/>group domain<br/>[groupController.js]"]
  node_backend_survey["Survey<br/>response capture"]
  node_backend_reco["Recommendations<br/>consensus engine"]
  node_backend_votes["Votes<br/>live decisioning<br/>[voteController.js]"]
  node_backend_collab["Trip tools<br/>supporting domains"]
  node_backend_models[("Mongo models<br/>Mongoose schemas")]
  node_backend_consensus{{"Consensus core<br/>deterministic logic<br/>[consensus.js]"}}
  node_backend_seed["Destinations<br/>seed data<br/>[destinations.json]"]
  node_backend_sockets(("Realtime sync<br/>Socket.io layer<br/>[journeySocket.js]"))
  node_backend_db[("MongoDB<br/>database<br/>[db.js]")]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["SPA<br/>React/Vite app<br/>[App.tsx]"]
  node_frontend_api["API layer<br/>Axios clients"]
  node_frontend_store["State stores<br/>Zustand stores"]
  node_frontend_socket(("Socket client<br/>realtime client<br/>[socket.ts]"))
  node_frontend_pages["Journey pages<br/>route views"]
  node_frontend_widgets["Collab widgets<br/>UI components"]
end

subgraph group_scanner["Aux service"]
  node_scanner_main["Bill scanner<br/>Python/FastAPI OCR<br/>[main.py]"]
end

node_frontend_app -->|"renders"| node_frontend_pages
node_frontend_pages -->|"calls"| node_frontend_api
node_frontend_pages -->|"reads/writes"| node_frontend_store
node_frontend_pages -->|"listens"| node_frontend_socket
node_frontend_widgets -->|"binds"| node_frontend_store
node_backend_server -->|"boots"| node_backend_app
node_backend_app -->|"routes"| node_backend_auth
node_backend_app -->|"routes"| node_backend_groups
node_backend_app -->|"routes"| node_backend_survey
node_backend_app -->|"routes"| node_backend_reco
node_backend_app -->|"routes"| node_backend_votes
node_backend_app -->|"routes"| node_backend_collab
node_backend_auth -->|"persists"| node_backend_models
node_backend_groups -->|"persists"| node_backend_models
node_backend_survey -->|"persists"| node_backend_models
node_backend_reco -->|"uses"| node_backend_consensus
node_backend_reco -->|"reads"| node_backend_seed
node_backend_reco -->|"persists"| node_backend_models
node_backend_votes -->|"persists"| node_backend_models
node_backend_collab -->|"persists"| node_backend_models
node_backend_sockets -->|"authenticates"| node_backend_auth
node_backend_sockets -->|"rooms"| node_backend_groups
node_backend_sockets -->|"broadcasts"| node_backend_survey
node_backend_sockets -->|"broadcasts"| node_backend_reco
node_backend_sockets -->|"broadcasts"| node_backend_votes
node_backend_models -->|"stores in"| node_backend_db
node_frontend_api -->|"requests"| node_backend_app
node_frontend_socket -->|"connects to"| node_backend_sockets
node_scanner_main -.->|"extends"| node_backend_collab

click node_frontend_app "https://github.com/raiyashu2004/nomadix/blob/main/frontend/src/App.tsx"
click node_frontend_api "https://github.com/raiyashu2004/nomadix/tree/main/frontend/src/api"
click node_frontend_store "https://github.com/raiyashu2004/nomadix/tree/main/frontend/src/store"
click node_frontend_socket "https://github.com/raiyashu2004/nomadix/blob/main/frontend/src/socket.ts"
click node_frontend_pages "https://github.com/raiyashu2004/nomadix/tree/main/frontend/src/pages"
click node_frontend_widgets "https://github.com/raiyashu2004/nomadix/tree/main/frontend/src/components"
click node_backend_server "https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/server.js"
click node_backend_app "https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/app.js"
click node_backend_auth "https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/controllers/authController.js"
click node_backend_groups "https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/controllers/groupController.js"
click node_backend_survey "https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/controllers/surveyController.js"
click node_backend_reco "https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/controllers/recommendationController.js"
click node_backend_votes "https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/controllers/voteController.js"
click node_backend_collab "https://github.com/raiyashu2004/nomadix/tree/main/BACKEND/src/controllers"
click node_backend_models "https://github.com/raiyashu2004/nomadix/tree/main/BACKEND/src/models"
click node_backend_consensus "https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/utils/consensus.js"
click node_backend_seed "https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/data/destinations.json"
click node_backend_sockets "https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/sockets/journeySocket.js"
click node_backend_db "https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/config/db.js"
click node_scanner_main "https://github.com/raiyashu2004/nomadix/blob/main/bill-scanner/main.py"

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_backend_server,node_backend_app,node_backend_auth,node_backend_groups,node_backend_survey,node_backend_reco,node_backend_votes,node_backend_collab,node_backend_models,node_backend_consensus,node_backend_seed,node_backend_sockets,node_backend_db toneBlue
class node_frontend_app,node_frontend_api,node_frontend_store,node_frontend_socket,node_frontend_pages,node_frontend_widgets toneAmber
class node_scanner_main toneMint
```

## Components

### Backend

Node.js/Express API, MongoDB persistence, consensus logic, and realtime synchronization.

- [Server](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/server.js): Express bootstrap · HTTP and socket server entrypoint for the backend application. · `BACKEND/src/server.js`
- [API app](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/app.js): Express app · Middleware, routing, and application wiring for the backend service. · `BACKEND/src/app.js`
- [Auth](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/controllers/authController.js): JWT access control · Registration, login, token generation, and protected request middleware. · `BACKEND/src/controllers/authController.js`
- [Groups](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/controllers/groupController.js): group domain · Group membership, coordination, and shared trip context. · `BACKEND/src/controllers/groupController.js`
- [Survey](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/controllers/surveyController.js): response capture · Collects member preferences used to build the group profile. · `BACKEND/src/controllers/surveyController.js`
- [Recommendations](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/controllers/recommendationController.js): consensus engine · Deterministic destination scoring and recommendation generation. · `BACKEND/src/controllers/recommendationController.js`
- [Votes](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/controllers/voteController.js): live decisioning · Stores and updates votes over generated recommendations. · `BACKEND/src/controllers/voteController.js`
- [Trip tools](https://github.com/raiyashu2004/nomadix/tree/main/BACKEND/src/controllers): supporting domains · Chat, itinerary, memories, parties, availability, and bills as broader trip-planning modules. · `BACKEND/src/controllers`
- [Mongo models](https://github.com/raiyashu2004/nomadix/tree/main/BACKEND/src/models): Mongoose schemas · Persistent domain entities for users, groups, surveys, recommendations, votes, and supporting trip data. · `BACKEND/src/models`
- [Consensus core](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/utils/consensus.js): deterministic logic · Computes group profiles and ranks destination seeds from local data. · `BACKEND/src/utils/consensus.js`
- [Destinations](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/data/destinations.json): seed data · Local destination catalog used by the recommendation algorithm. · `BACKEND/src/data/destinations.json`
- [Realtime sync](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/sockets/journeySocket.js): Socket.io layer · Authenticated sockets, room membership, and broadcasts for survey, recommendation, and vote events. · `BACKEND/src/sockets/journeySocket.js`
- [MongoDB](https://github.com/raiyashu2004/nomadix/blob/main/BACKEND/src/config/db.js): database · Primary persistent store accessed through Mongoose. · `BACKEND/src/config/db.js`

### Frontend

React/TypeScript SPA with REST clients, stores, and collaborative UI.

- [SPA](https://github.com/raiyashu2004/nomadix/blob/main/frontend/src/App.tsx): React/Vite app · Main client application shell and route composition. · `frontend/src/App.tsx`
- [API layer](https://github.com/raiyashu2004/nomadix/tree/main/frontend/src/api): Axios clients · Typed REST wrappers for auth, groups, survey, recommendations, votes, and memories. · `frontend/src/api`
- [State stores](https://github.com/raiyashu2004/nomadix/tree/main/frontend/src/store): Zustand stores · Client-side state for auth, chat, consensus, itinerary, expenses, memories, and party flow. · `frontend/src/store`
- [Socket client](https://github.com/raiyashu2004/nomadix/blob/main/frontend/src/socket.ts): realtime client · Singleton client for live group updates and collaborative synchronization. · `frontend/src/socket.ts`
- [Journey pages](https://github.com/raiyashu2004/nomadix/tree/main/frontend/src/pages): route views · Login, register, dashboard, consensus, and party screens that drive the main user flow. · `frontend/src/pages`
- [Collab widgets](https://github.com/raiyashu2004/nomadix/tree/main/frontend/src/components): UI components · Shared collaboration surfaces such as chat, itinerary, bill split, gallery, and voting progress. · `frontend/src/components`

### Aux service

Separate Python service for bill scanning and OCR-related automation.

- [Bill scanner](https://github.com/raiyashu2004/nomadix/blob/main/bill-scanner/main.py): Python/FastAPI OCR · Separate auxiliary service for receipt scanning and expense automation. · `bill-scanner/main.py`

## Connections

- SPA → Journey pages: renders · The SPA composes the main journey pages.
- Journey pages → API layer: calls · Pages use REST clients for backend data.
- Journey pages → State stores: reads/writes · Views synchronize through shared Zustand state.
- Journey pages → Socket client: listens · Pages react to live collaboration events.
- Collab widgets → State stores: binds · Widgets read and update shared client state.
- Server → API app: boots · Server starts the Express application.
- API app → Auth: routes · Authentication endpoints are mounted in the API app.
- API app → Groups: routes · Group endpoints are mounted in the API app.
- API app → Survey: routes · Survey endpoints are mounted in the API app.
- API app → Recommendations: routes · Recommendation endpoints are mounted in the API app.
- API app → Votes: routes · Vote endpoints are mounted in the API app.
- API app → Trip tools: routes · Supporting trip-planning endpoints are mounted in the API app.
- Auth → Mongo models: persists · Auth reads and writes user records.
- Groups → Mongo models: persists · Group state is stored through Mongoose models.
- Survey → Mongo models: persists · Survey responses are stored as domain records.
- Recommendations → Consensus core: uses · Recommendation generation is driven by deterministic consensus logic.
- Recommendations → Destinations: reads · The engine scores local destination seed data.
- Recommendations → Mongo models: persists · Generated recommendations are saved to the database.
- Votes → Mongo models: persists · Votes are recorded as domain data.
- Trip tools → Mongo models: persists · Supporting trip tools use the shared persistence layer.
- Realtime sync → Auth: authenticates · Socket connections are verified with JWT-backed auth.
- Realtime sync → Groups: rooms · Users join group rooms for live updates.
- Realtime sync → Survey: broadcasts · Survey submissions are emitted to connected clients.
- Realtime sync → Recommendations: broadcasts · Recommendation generation events are broadcast live.
- Realtime sync → Votes: broadcasts · Vote updates are pushed to the room.
- Mongo models → MongoDB: stores in · Mongoose models persist to MongoDB.
- API layer → API app: requests · REST calls target the backend API.
- Socket client → Realtime sync: connects to · Client sockets receive live broadcasts from the backend.
- Bill scanner → Trip tools: extends · Auxiliary OCR service complements trip expense workflows.