# krishnaacharyaa/wanderlust architecture

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

- Interactive diagram: https://gitdiagram.com/krishnaacharyaa/wanderlust
- Repository: https://github.com/krishnaacharyaa/wanderlust

## Overview

##### Project type and purpose
- Wanderlust is a full‑stack travel‑blog application built on the MERN stack (MongoDB, Express.js, React, Node.js) with TypeScript. Its goal is to let users browse and create travel posts, manage user authentication, and explore posts by category.

##### File structure
- Top‑level directories:
- backend/ – an Express‑based REST API in TypeScript
- frontend/ – a Vite‑powered React SPA in TypeScript
- Patterns and layers in backend:
- config/ – DB and Passport configuration
- models/ – Mongoose schemas (user, post)
- controllers/ – business logic for auth, posts, user
- services/ – auxiliary services (Redis cache)
- routes/ – API endpoints grouped by feature
- middlewares/ – authentication, error handling, validation
- utils/ – error/response wrappers, async handlers, constants
- Frontend structure follows component‑driven design:
- src/components/ – reusable UI pieces (cards, skeletons, modal, theme toggle)
- src/pages/ – route‑level page components (home, details, signin, signup, admin)
- src/hooks & src/helpers – custom hooks and Axios instance
- src/utils – UI‑related utilities (slug, theme)
- Deployment/config: Vercel configuration at both root and each package; GitHub Actions workflows for CI.

##### Key insights from the README
- Describes the MERN stack, learning focus, React mastery, key features (featured posts, topic categories).

##### Main components and interactions
a. Components
1. Client (React SPA)
2. API Server (Express/Node)
3. Database (MongoDB)
4. Cache (Redis)
5. External auth library (Passport.js with JWT/cookie)
6. Static asset store (if any) / Vercel hosting
7. Third‑party services (e.g., email provider, analytics) – optional
b. Relationships & data flow
- Client sends HTTPS requests (via Axios) to the API Server endpoints.
- API Server applies middleware (auth, validation), invokes controllers.
- Controllers query MongoDB directly or via a Redis cache layer for “posts” data (cache‑aside pattern).
- Passport middleware handles session or JWT validation on protected routes.
- API Server returns JSON responses to Client; client updates UI state.
- Frontend uses React Router for navigation, custom hooks for auth state, and theme utilities.
c. Architectural patterns & principles
- MVC‑inspired layering in the backend (models/controllers/services/routes).
- Cache‑aside strategy: services/cache‑posts.ts checks Redis before hitting the DB.
- Separation of concerns: UI components vs. page containers vs. API utilities.
- Env‑based configurations (.env.sample, tsconfig variants).
d. Technologies & frameworks
- Frontend: React, Vite, TypeScript, Tailwind CSS, Jest + React Testing Library
- Backend: Node.js, Express, TypeScript, Mongoose, Redis, Passport, Jest + supertest

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React SPA)"
        direction TB
        ReactSPA["React SPA"]:::compute
        Pages["Pages"]:::compute
        Components["Components"]:::compute
        AxiosInstance["Axios Instance"]:::compute
        AuthHook["useAuthData Hook"]:::compute
        ThemeUtils["Theme Utils"]:::compute
    end

    %% Backend Layer
    subgraph "Backend (Express API)"
        direction TB
        ExpressAPI["Express API (Node.js)"]:::compute
        subgraph "Configuration"
            DBConfig["DB Config"]:::config
            PassportConfig["Passport Config"]:::auth
        end
        subgraph "Middlewares"
            AuthMiddleware["Auth Middleware"]:::auth
            ErrorMiddleware["Error Middleware"]:::compute
            PostMiddleware["Post Validation"]:::compute
        end
        subgraph "Routes"
            AuthRoutes["Auth Routes"]:::compute
            UserRoutes["User Routes"]:::compute
            PostRoutes["Post Routes"]:::compute
        end
        subgraph "Controllers"
            AuthController["Auth Controller"]:::compute
            UserController["User Controller"]:::compute
            PostsController["Posts Controller"]:::compute
        end
        subgraph "Services & Utils"
            RedisService["Redis Service"]:::cache
            CachePosts["Cache Posts Util"]:::cache
            AsyncHandler["Async Handler"]:::compute
            ApiError["API Error"]:::compute
            ApiResponse["API Response"]:::compute
            Constants["Constants"]:::compute
            CookieOpts["Cookie Options"]:::compute
        end
        subgraph "Models"
            UserModel["User Model"]:::db
            PostModel["Post Model"]:::db
        end
    end

    %% Data Stores
    MongoDB["MongoDB"]:::db
    Redis["Redis Cache"]:::cache

    %% Optional Integrations
    EmailService["Email Provider"]:::external
    Analytics["Analytics"]:::external

    %% Hosting
    subgraph "Hosting (Vercel)"
        direction TB
        ReactSPA
        ExpressAPI
    end

    %% Connections
    ReactSPA -->|HTTP Requests| ExpressAPI
    ExpressAPI -->|uses| AuthMiddleware
    AuthMiddleware -->|protects| AuthRoutes
    ExpressAPI -->|uses| ErrorMiddleware
    ExpressAPI -->|routes| AuthRoutes
    ExpressAPI -->|routes| UserRoutes
    ExpressAPI -->|routes| PostRoutes

    AuthRoutes --> AuthController
    UserRoutes --> UserController
    PostRoutes --> PostsController

    AuthController -->|JWT/Cookie| PassportConfig
    PostsController -->|cache-aside| CachePosts
    CachePosts --> RedisService
    RedisService --> Redis
    PostsController -->|read/write| MongoDB
    UserController -->|read/write| MongoDB

    PostsController --> UserModel
    PostsController --> PostModel
    UserController --> UserModel

    %% Frontend internals
    ReactSPA --> Pages
    ReactSPA --> Components
    ReactSPA --> AxiosInstance
    ReactSPA --> AuthHook
    ReactSPA --> ThemeUtils

    %% Optional dashed integrations
    ExpressAPI -.->|email| EmailService
    ExpressAPI -.->|analytics| Analytics

    %% Click Events
    click ReactSPA "https://github.com/krishnaacharyaa/wanderlust/blob/main/frontend/src/App.tsx"
    click Pages "https://github.com/krishnaacharyaa/wanderlust/tree/main/frontend/src/pages"
    click Components "https://github.com/krishnaacharyaa/wanderlust/tree/main/frontend/src/components"
    click AxiosInstance "https://github.com/krishnaacharyaa/wanderlust/blob/main/frontend/src/helpers/axios-instance.ts"
    click AuthHook "https://github.com/krishnaacharyaa/wanderlust/blob/main/frontend/src/hooks/useAuthData.ts"
    click ThemeUtils "https://github.com/krishnaacharyaa/wanderlust/tree/main/frontend/src/utils"

    click ExpressAPI "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/app.ts"
    click DBConfig "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/config/db.ts"
    click PassportConfig "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/config/passport.ts"
    click AuthMiddleware "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/middlewares/auth-middleware.ts"
    click ErrorMiddleware "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/middlewares/error-middleware.ts"
    click PostMiddleware "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/middlewares/post-middleware.ts"
    click AuthRoutes "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/routes/auth.ts"
    click UserRoutes "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/routes/user.ts"
    click PostRoutes "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/routes/posts.ts"
    click AuthController "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/controllers/auth-controller.ts"
    click UserController "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/controllers/user-controller.ts"
    click PostsController "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/controllers/posts-controller.ts"
    click RedisService "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/services/redis.ts"
    click CachePosts "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/utils/cache-posts.ts"
    click AsyncHandler "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/utils/async-handler.ts"
    click ApiError "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/utils/api-error.ts"
    click ApiResponse "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/utils/api-response.ts"
    click Constants "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/utils/constants.ts"
    click CookieOpts "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/utils/cookie_options.ts"
    click UserModel "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/models/user.ts"
    click PostModel "https://github.com/krishnaacharyaa/wanderlust/blob/main/backend/models/post.ts"

    %% Styles
    classDef compute fill:#B3CDE3,stroke:#333,stroke-width:1px
    classDef db fill:#FBB4AE,stroke:#333,stroke-width:1px
    classDef cache fill:#CCEBC5,stroke:#333,stroke-width:1px
    classDef auth fill:#DECBE4,stroke:#333,stroke-width:1px
    classDef config fill:#FED9A6,stroke:#333,stroke-width:1px
    classDef external stroke-dasharray: 5 5,fill:#FFFFFF,stroke:#666,stroke-width:1px
```
