How raiyashu2004/nomadix works
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: app.js API app · models Mongo models · journeySocket.js Realtime sync · recommendationController.js Recommendations
Components 20
Backend
Node.js/Express API, MongoDB persistence, consensus logic, and realtime synchronization.
- Server · HTTP and socket server entrypoint for the backend application.
BACKEND/src/server.js - API app · Middleware, routing, and application wiring for the backend service.
BACKEND/src/app.js - Auth · Registration, login, token generation, and protected request middleware.
BACKEND/src/controllers/authController.js - Groups · Group membership, coordination, and shared trip context.
BACKEND/src/controllers/groupController.js - Survey · Collects member preferences used to build the group profile.
BACKEND/src/controllers/surveyController.js - Recommendations · Deterministic destination scoring and recommendation generation.
BACKEND/src/controllers/recommendationController.js - Votes · Stores and updates votes over generated recommendations.
BACKEND/src/controllers/voteController.js - Trip tools · Chat, itinerary, memories, parties, availability, and bills as broader trip-planning modules.
BACKEND/src/controllers - Mongo models · Persistent domain entities for users, groups, surveys, recommendations, votes, and supporting trip data.
BACKEND/src/models - Consensus core · Computes group profiles and ranks destination seeds from local data.
BACKEND/src/utils/consensus.js - Destinations · Local destination catalog used by the recommendation algorithm.
BACKEND/src/data/destinations.json - Realtime sync · Authenticated sockets, room membership, and broadcasts for survey, recommendation, and vote events.
BACKEND/src/sockets/journeySocket.js - MongoDB · Primary persistent store accessed through Mongoose.
BACKEND/src/config/db.js
Frontend
React/TypeScript SPA with REST clients, stores, and collaborative UI.
- SPA · Main client application shell and route composition.
frontend/src/App.tsx - API layer · Typed REST wrappers for auth, groups, survey, recommendations, votes, and memories.
frontend/src/api - State stores · Client-side state for auth, chat, consensus, itinerary, expenses, memories, and party flow.
frontend/src/store - Socket client · Singleton client for live group updates and collaborative synchronization.
frontend/src/socket.ts - Journey pages · Login, register, dashboard, consensus, and party screens that drive the main user flow.
frontend/src/pages - Collab widgets · 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 · Separate auxiliary service for receipt scanning and expense automation.
bill-scanner/main.py
Connections 29
- 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.