# naveenxyz/rides architecture

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

- Interactive diagram: https://gitdiagram.com/naveenxyz/rides
- Repository: https://github.com/naveenxyz/rides

## Overview

##### Project Type and Purpose
- BangaRide is a full-stack web application: a React/TypeScript single-page frontend served via Vite (and optionally Nginx/Docker) and a NestJS/TypeORM backend exposing a REST API, persisting data to PostgreSQL.
- It provides spot discovery, trip planning, user authentication (Google OAuth + JWT), commenting, rating, and trip-completion tracking for motorcycle enthusiasts in Bangalore.

##### File Structure
- Top level:
- Frontend: index.html, src/, public config files (tailwind.config.js, postcss.config.js, vite.config.ts).
- Backend (“server” folder): NestJS modules under server/src (auth, users, spots, trips, comments), TypeORM entities, main.ts, server package/config files.
- Deployment/config: Dockerfile, docker-compose.yml, nginx.conf, .env templates.
- Architectural hints: monolithic NestJS backend organized by feature modules (Auth, Users, Spots, Trips, Comments), React context for global auth state, React Router for pages.

##### Main Components
a. Client Browser & UI Layer
- React SPA (App.tsx, pages/, components/, Tailwind for styling).
- Communicates via HTTP/HTTPS to backend API.
b. Reverse Proxy / Static Server (optional)
- Nginx (nginx.conf) or Vite dev server serves static assets and proxies API calls to NestJS.
c. API Layer (NestJS Backend)
- Auth Module: Google OAuth (Passport.js strategies), JWT issuance/validation, guard + custom decorators.
- Feature Modules: Users, Spots, Trips, Comments. Each has Controller → Service → Entity (via TypeORM).
d. Data Layer
- PostgreSQL database managed via TypeORM entities (user, spot, trip, comment).
e. External Service
- Google OAuth endpoints for user authentication.

##### Relationships and Interactions
- User → Browser/UI: interacts with pages (login, browse spots/trips, comment, rate).
- UI → Nginx/Vite Server: fetches static assets; API calls routed to backend (e.g., GET /api/spots).
- Backend → DB: TypeORM executes SQL queries against PostgreSQL.
- Backend ↔ Google OAuth: Passport.js strategy calls Google for login → callback → JWT issuance.
- UI ↔ Backend: includes JWT in Authorization headers for protected endpoints.

##### Architectural Patterns and Design Principles
- Separation of Concerns: frontend UI vs. backend API vs. database.
- Modular monolith in backend: feature modules in NestJS (Auth, Users, Spots, Trips, Comments).
- Layered architecture in backend: Controllers (HTTP endpoints) → Services (business logic) → Repositories/entities (data access).
- Token-based stateless authentication: JWT tokens signed/verified per request.
- Externalized configuration: .env files for both frontend and backend.

##### Key Technologies and Frameworks
- Frontend: React, React Router, TypeScript, Vite, Tailwind CSS, Lucide React, Context API for auth, Axios or fetch in api.ts.
- Backend: NestJS, TypeORM, PostgreSQL, Passport.js (Google OAuth strategy), JWT.
- DevOps/Deployment: Docker, docker-compose, Nginx.

##### Final Checklist
- Notes on environment/config (.env for secrets, variables).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Browser & UI Layer" 
        direction TB
        Browser["User Browser"]:::frontend
        IndexHTML["index.html"]:::frontend
        App["App.tsx"]:::frontend
        Pages["src/pages/"]:::frontend
        Components["src/components/"]:::frontend
        AuthCtx["src/context/AuthContext.tsx"]:::frontend
        APIService["src/services/api.ts"]:::frontend
        TailwindCfg["tailwind.config.js"]:::frontend
        ViteCfg["vite.config.ts"]:::frontend
    end

    %% Infrastructure Layer
    subgraph "Reverse Proxy / Static Server" 
        direction TB
        Nginx["Nginx Server"]:::infra
        Dockerfile["Dockerfile"]:::infra
        DockerCompose["docker-compose.yml"]:::infra
    end

    %% API Layer
    subgraph "API Server (NestJS)" 
        direction TB
        MainTS["server/src/main.ts"]:::backend
        AppModule["server/src/app.module.ts"]:::backend

        subgraph "Auth Module" 
            direction TB
            AuthModule["auth.module.ts"]:::backend
            AuthCtrl["auth.controller.ts"]:::backend
            AuthService["auth.service.ts"]:::backend
            GoogleStrat["strategies/google.strategy.ts"]:::backend
            JWTStrat["strategies/jwt.strategy.ts"]:::backend
            JWTGuard["guards/jwt-auth.guard.ts"]:::backend
            GetUserDec["decorators/get-user.decorator.ts"]:::backend
            GoogleDTO["dto/google-login.dto.ts"]:::backend
        end

        subgraph "Users Module"
            direction TB
            UsersModule["users.module.ts"]:::backend
            UsersCtrl["users.controller.ts"]:::backend
            UsersService["users.service.ts"]:::backend
            UserEntity["entities/user.entity.ts"]:::backend
        end

        subgraph "Spots Module"
            direction TB
            SpotsModule["spots.module.ts"]:::backend
            SpotsCtrl["spots.controller.ts"]:::backend
            SpotsService["spots.service.ts"]:::backend
            SpotEntity["entities/spot.entity.ts"]:::backend
        end

        subgraph "Trips Module"
            direction TB
            TripsModule["trips.module.ts"]:::backend
            TripsCtrl["trips.controller.ts"]:::backend
            TripsService["trips.service.ts"]:::backend
            TripEntity["entities/trip.entity.ts"]:::backend
        end

        subgraph "Comments Module"
            direction TB
            CommentsModule["comments.module.ts"]:::backend
            CommentsCtrl["comments.controller.ts"]:::backend
            CommentsService["comments.service.ts"]:::backend
            CommentEntity["entities/comment.entity.ts"]:::backend
        end
    end

    %% Data & External
    subgraph Infrastructure
        direction TB
        Postgres["PostgreSQL Database"]:::database
    end

    GoogleOAuth["Google OAuth Service"]:::external

    %% Connections
    Browser -->|"GET index.html, static assets"| Nginx
    Nginx -->|"serves static assets"| Browser
    Browser -->|"HTTP REST /api/** + JWT"| MainTS
    MainTS -->|"SQL queries via TypeORM"| Postgres
    MainTS -->|"OAuth2 handshake"| GoogleOAuth
    Browser -->|"OAuth redirect"| GoogleOAuth
    GoogleOAuth -->|"callback with code"| MainTS
    Browser -->|"Store JWT in Context/localStorage"| AuthCtx

    %% Docker orchestration
    DockerCompose --> Nginx
    DockerCompose --> MainTS
    DockerCompose --> Postgres

    %% Click Events
    click IndexHTML "https://github.com/naveenxyz/rides/blob/main/index.html"
    click App "https://github.com/naveenxyz/rides/blob/main/src/App.tsx"
    click Pages "https://github.com/naveenxyz/rides/tree/main/src/pages/"
    click Components "https://github.com/naveenxyz/rides/tree/main/src/components/"
    click AuthCtx "https://github.com/naveenxyz/rides/blob/main/src/context/AuthContext.tsx"
    click APIService "https://github.com/naveenxyz/rides/blob/main/src/services/api.ts"
    click TailwindCfg "https://github.com/naveenxyz/rides/blob/main/tailwind.config.js"
    click ViteCfg "https://github.com/naveenxyz/rides/blob/main/vite.config.ts"
    click Nginx "https://github.com/naveenxyz/rides/blob/main/nginx.conf"
    click Dockerfile "https://github.com/naveenxyz/rides/tree/main/Dockerfile"
    click DockerCompose "https://github.com/naveenxyz/rides/blob/main/docker-compose.yml"
    click MainTS "https://github.com/naveenxyz/rides/blob/main/server/src/main.ts"
    click AppModule "https://github.com/naveenxyz/rides/blob/main/server/src/app.module.ts"
    click AuthModule "https://github.com/naveenxyz/rides/blob/main/server/src/auth/auth.module.ts"
    click AuthCtrl "https://github.com/naveenxyz/rides/blob/main/server/src/auth/auth.controller.ts"
    click AuthService "https://github.com/naveenxyz/rides/blob/main/server/src/auth/auth.service.ts"
    click GoogleStrat "https://github.com/naveenxyz/rides/blob/main/server/src/auth/strategies/google.strategy.ts"
    click JWTStrat "https://github.com/naveenxyz/rides/blob/main/server/src/auth/strategies/jwt.strategy.ts"
    click JWTGuard "https://github.com/naveenxyz/rides/blob/main/server/src/auth/guards/jwt-auth.guard.ts"
    click GetUserDec "https://github.com/naveenxyz/rides/blob/main/server/src/auth/decorators/get-user.decorator.ts"
    click GoogleDTO "https://github.com/naveenxyz/rides/blob/main/server/src/auth/dto/google-login.dto.ts"
    click UsersModule "https://github.com/naveenxyz/rides/blob/main/server/src/users/users.module.ts"
    click UsersCtrl "https://github.com/naveenxyz/rides/blob/main/server/src/users/users.controller.ts"
    click UsersService "https://github.com/naveenxyz/rides/blob/main/server/src/users/users.service.ts"
    click UserEntity "https://github.com/naveenxyz/rides/blob/main/server/src/users/entities/user.entity.ts"
    click SpotsModule "https://github.com/naveenxyz/rides/blob/main/server/src/spots/spots.module.ts"
    click SpotsCtrl "https://github.com/naveenxyz/rides/blob/main/server/src/spots/spots.controller.ts"
    click SpotsService "https://github.com/naveenxyz/rides/blob/main/server/src/spots/spots.service.ts"
    click SpotEntity "https://github.com/naveenxyz/rides/blob/main/server/src/spots/entities/spot.entity.ts"
    click TripsModule "https://github.com/naveenxyz/rides/blob/main/server/src/trips/trips.module.ts"
    click TripsCtrl "https://github.com/naveenxyz/rides/blob/main/server/src/trips/trips.controller.ts"
    click TripsService "https://github.com/naveenxyz/rides/blob/main/server/src/trips/trips.service.ts"
    click TripEntity "https://github.com/naveenxyz/rides/blob/main/server/src/trips/entities/trip.entity.ts"
    click CommentsModule "https://github.com/naveenxyz/rides/blob/main/server/src/comments/comments.module.ts"
    click CommentsCtrl "https://github.com/naveenxyz/rides/blob/main/server/src/comments/comments.controller.ts"
    click CommentsService "https://github.com/naveenxyz/rides/blob/main/server/src/comments/comments.service.ts"
    click CommentEntity "https://github.com/naveenxyz/rides/blob/main/server/src/comments/entities/comment.entity.ts"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#64B5F6,color:#0D47A1;
    classDef infra fill:#ECEFF1,stroke:#90A4AE,color:#37474F;
    classDef backend fill:#FFF3E0,stroke:#FFB74D,color:#E65100;
    classDef database fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20;
    classDef external fill:#F3E5F5,stroke:#CE93D8,color:#4A148C;
```
