# himavarshithreddy/mongosnap architecture

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

- Interactive diagram: https://gitdiagram.com/himavarshithreddy/mongosnap
- Repository: https://github.com/himavarshithreddy/mongosnap

## Overview

1. **Repository shape**
   - MongoSnap is a two-app monorepo: `apps/frontend` is the React/Vite client, and `apps/backend` is the Node.js/Express API.
   - The root workspace (`pnpm-workspace.yaml`, root `package.json`) ties the two together, and deployment is automated via GitHub Actions plus `deploy.sh`.

2. **Overall system boundary**
   - The frontend is the user-facing shell for authentication, query building, schema browsing, billing, and support.
   - The backend is the trust boundary: it owns authentication, authorization, database connections, query execution, AI prompt handling, payments, email, and persistence to MongoDB.

3. **Primary request flow**
   - A user logs in on the React app, which stores session/auth state in `UserContext` and route guards in `ProtectedRoutes`.
   - Authenticated screens such as `QueryInterface`, `SchemaExplorer`, `SavedQuery`/history views, and `Settings` call backend APIs.
   - The backend validates the user, checks usage/limits, performs the requested operation, and returns results for rendering in the client.

4. **Core application domain**
   - The central product is MongoDB query generation and management.
   - `utils/geminiApi.js` suggests AI-assisted generation of MongoDB queries from natural language.
   - `utils/queryExecutor.js` and `utils/databaseManager.js` indicate that the backend can connect to user-provided MongoDB instances, inspect schemas, and execute queries on behalf of the user.

5. **Persistence layer**
   - The backend uses Mongoose models for the application’s state: `User`, `Connection`, `SavedQuery`, `QueryHistory`, `UserUsage`, and `RefreshToken`.
   - Supporting records include `BugReport`, `Contact`, `PaymentTransaction`, and likely security/verification state via auth-related models.
   - MongoDB Atlas is the persistent store for both account data and operational records.

6. **Authentication and session security**
   - Authentication is split across dedicated routes: `auth.js`, `oauth.js`, `forgotpassword.js`, `verify.js`, `twofactor.js`, and middleware.
   - The presence of `RefreshToken` and `totpgenerator.js` indicates token refresh plus 2FA/TOTP support.
   - The frontend has dedicated login/reset/OAuth pages and protected routes, so the app separates public marketing/auth flows from the authenticated workspace.

7. **Payments and premium access**
   - Premium “SnapX” access is managed through the payment subsystem: `payment.js`, `PaymentTransaction`, `PaymentHelper.js`, `paymentUtils.js`, and `cashfree.js`.
   - Cashfree is the external payment gateway, and the backend likely verifies payment callbacks before activating subscription status or lifting usage limits.
   - The frontend includes payment and success/failure pages plus upgrade prompts tied to usage limits.

8. **Notifications and support**
   - `utils/mailer.js` handles transactional email, with the README calling out Brevo/SMTP for verification, password reset, login alerts, and related notifications.
   - In-app support is modeled as `BugReport` and `Contact` routes/models, with admin-facing UI components for reviewing submissions.

9. **Frontend structure**
   - The client is organized by concern: reusable UI in `components`, route-level screens in `pages`, auth state in `contexts`, and policy content in `data`.
   - Main app surfaces include the public marketing site, login/signup, the query playground, pricing, settings, payment, OAuth flows, and policy pages.
   - Components like `QueryInterface`, `SchemaExplorer`, `SessionManager`, `QueryHistory`, and `UsageLimitPrompt` reflect the product’s core workflow: inspect, generate, run, and manage queries.

10. **Operational and workflow boundaries**
   - The backend has an `uploads` directory containing at least one uploaded collection archive, so file import/export is part of the operational surface.
   - `routes/test.js` and the CI/deploy files suggest separate testing/deployment concerns from the product API itself.
   - Hosting is described as AWS for the app and MongoDB Atlas for data, with HTTPS, CORS, rate limiting, CSRF, JWT, and 2FA forming the security envelope around the service.

11. **How to draw the architecture**
   - Place the React/Vite frontend at the edge, talking over HTTP to an Express API.
   - Put MongoDB Atlas behind the API as the primary datastore.
   - Show external integrations off the backend: Gemini for AI generation, Cashfree for payments, SMTP/Brevo for email.
   - Emphasize that the backend is not just CRUD; it is the orchestration layer for query execution, account security, billing, and usage enforcement.

Main entry points: [`apps/backend/index.js`](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/index.js) (API app), [`apps/frontend`](https://github.com/himavarshithreddy/mongosnap/tree/main/apps/frontend) (Client app), [`apps/backend/utils/queryExecutor.js`](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/utils/queryExecutor.js) (Query service), [`apps/backend/utils/databaseManager.js`](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/utils/databaseManager.js) (DB manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
  node_root["MongoSnap<br/>workspace"]
  node_workspace["Workspace<br/>pnpm"]
  node_deploy["Deploy<br/>ci/cd<br/>[deploy.yml]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["Client app<br/>react/vite"]
  node_public_shell["Public shell<br/>layout<br/>[PublicLayout.jsx]"]
  node_auth_state["Auth state<br/>context/guard<br/>[UserContext.jsx]"]
  node_playground_ui["Playground<br/>query ui<br/>[QueryInterface.jsx]"]
  node_admin_support["Admin support<br/>support ui"]
  node_billing_ui["Billing UI<br/>premium ui<br/>[Payment.jsx]"]
  node_policy_pages["Policy pages<br/>content"]
end

subgraph group_backend["Backend"]
  node_backend_app["API app<br/>express/api<br/>[index.js]"]
  node_auth_routes["Auth routes<br/>[auth.js]"]
  node_domain_routes["Domain routes<br/>[connection.js]"]
  node_payment_routes["Payments<br/>billing<br/>[payment.js]"]
  node_security_mw["Security<br/>middleware<br/>[middleware.js]"]
  node_query_service["Query service<br/>query orchestration<br/>[queryExecutor.js]"]
  node_db_manager["DB manager<br/>connection layer<br/>[databaseManager.js]"]
  node_ai_service["AI helper<br/>genai<br/>[geminiApi.js]"]
  node_payment_core["Payment core<br/>payments<br/>[PaymentHelper.js]"]
  node_mail_service["Mail service<br/>notifications<br/>[mailer.js]"]
  node_models[("Data models<br/>mongoose models<br/>[User.js]")]
end

subgraph group_external["Integrations"]
  node_mongo_atlas[("MongoDB Atlas<br/>datastore")]
  node_gemini(("Gemini<br/>external ai"))
  node_cashfree(("Cashfree<br/>payment gateway"))
  node_smtp(("SMTP/Brevo<br/>email service"))
  node_github_actions(("GitHub Actions<br/>ci service"))
end

node_root -->|"defines"| node_workspace
node_root -->|"automates"| node_deploy
node_root -->|"contains"| node_frontend_app
node_root -->|"contains"| node_backend_app
node_deploy -->|"runs on"| node_github_actions
node_frontend_app -->|"renders"| node_public_shell
node_frontend_app -->|"tracks session"| node_auth_state
node_frontend_app -->|"drives"| node_playground_ui
node_frontend_app -->|"exposes"| node_admin_support
node_frontend_app -->|"handles"| node_billing_ui
node_frontend_app -->|"shows"| node_policy_pages
node_frontend_app -->|"calls api"| node_backend_app
node_backend_app -->|"routes"| node_auth_routes
node_backend_app -->|"routes"| node_domain_routes
node_backend_app -->|"routes"| node_payment_routes
node_backend_app -->|"guards"| node_security_mw
node_backend_app -->|"orchestrates"| node_query_service
node_backend_app -->|"connects"| node_db_manager
node_backend_app -->|"uses"| node_ai_service
node_backend_app -->|"uses"| node_payment_core
node_backend_app -->|"uses"| node_mail_service
node_backend_app -->|"persists via"| node_models
node_query_service -->|"depends on"| node_db_manager
node_query_service -->|"consults"| node_ai_service
node_payment_core -->|"integrates"| node_cashfree
node_mail_service -->|"delivers via"| node_smtp
node_models -->|"stores in"| node_mongo_atlas
node_db_manager -->|"connects to"| node_mongo_atlas
node_ai_service -->|"calls"| node_gemini

click node_workspace "https://github.com/himavarshithreddy/mongosnap/blob/main/pnpm-workspace.yaml"
click node_deploy "https://github.com/himavarshithreddy/mongosnap/blob/main/.github/workflows/deploy.yml"
click node_frontend_app "https://github.com/himavarshithreddy/mongosnap/tree/main/apps/frontend"
click node_public_shell "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/frontend/src/components/PublicLayout.jsx"
click node_auth_state "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/frontend/src/contexts/UserContext.jsx"
click node_playground_ui "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/frontend/src/components/QueryInterface.jsx"
click node_admin_support "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/frontend/src/components/AdminBugReports.jsx"
click node_billing_ui "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/frontend/src/components/Payment.jsx"
click node_policy_pages "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/frontend/src/data/privacyPolicyContent.js"
click node_backend_app "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/index.js"
click node_auth_routes "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/routes/auth.js"
click node_domain_routes "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/routes/connection.js"
click node_payment_routes "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/routes/payment.js"
click node_security_mw "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/routes/middleware.js"
click node_query_service "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/utils/queryExecutor.js"
click node_db_manager "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/utils/databaseManager.js"
click node_ai_service "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/utils/geminiApi.js"
click node_payment_core "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/utils/PaymentHelper.js"
click node_mail_service "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/utils/mailer.js"
click node_models "https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/models/User.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_root,node_workspace,node_deploy toneBlue
class node_frontend_app,node_public_shell,node_auth_state,node_playground_ui,node_admin_support,node_billing_ui,node_policy_pages toneAmber
class node_backend_app,node_auth_routes,node_domain_routes,node_payment_routes,node_security_mw,node_query_service,node_db_manager,node_ai_service,node_payment_core,node_mail_service,node_models toneMint
class node_mongo_atlas,node_gemini,node_cashfree,node_smtp,node_github_actions toneRose
```

## Components

### Monorepo

Workspace and deployment glue for both apps.

- **MongoSnap**: workspace · Two-app monorepo for MongoDB query generation and management.
- [Workspace](https://github.com/himavarshithreddy/mongosnap/blob/main/pnpm-workspace.yaml): pnpm · Root package and workspace configuration. · `pnpm-workspace.yaml`
- [Deploy](https://github.com/himavarshithreddy/mongosnap/blob/main/.github/workflows/deploy.yml): ci/cd · GitHub Actions workflow and deploy script. · `.github/workflows/deploy.yml`

### Frontend

React/Vite client and user workspace.

- [Client app](https://github.com/himavarshithreddy/mongosnap/tree/main/apps/frontend): react/vite · Browser application for authentication, query workflows, billing, and support. · `apps/frontend`
- [Public shell](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/frontend/src/components/PublicLayout.jsx): layout · Public pages and shared layout for marketing and auth entry points. · `apps/frontend/src/components/PublicLayout.jsx`
- [Auth state](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/frontend/src/contexts/UserContext.jsx): context/guard · Client session state and protected route gating. · `apps/frontend/src/contexts/UserContext.jsx`
- [Playground](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/frontend/src/components/QueryInterface.jsx): query ui · Query interface, schema browsing, history, session, and usage prompts. · `apps/frontend/src/components/QueryInterface.jsx`
- [Admin support](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/frontend/src/components/AdminBugReports.jsx): support ui · Bug reports, contact submissions, and review surfaces. · `apps/frontend/src/components/AdminBugReports.jsx`
- [Billing UI](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/frontend/src/components/Payment.jsx): premium ui · Upgrade, payment, and success/failure flows for SnapX access. · `apps/frontend/src/components/Payment.jsx`
- [Policy pages](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/frontend/src/data/privacyPolicyContent.js): content · Terms, privacy, and refund content rendered in-app. · `apps/frontend/src/data/privacyPolicyContent.js`

### Backend

Express API, business logic, and persistence boundary.

- [API app](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/index.js): express/api · Node.js Express service that owns trust, orchestration, and persistence. · `apps/backend/index.js`
- [Auth routes](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/routes/auth.js): routes · Login, OAuth, password reset, verification, and 2FA endpoints. · `apps/backend/routes/auth.js`
- [Domain routes](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/routes/connection.js): routes · Connection, query history, bug report, contact, and test endpoints. · `apps/backend/routes/connection.js`
- [Payments](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/routes/payment.js): billing · Subscription and transaction handling for premium access. · `apps/backend/routes/payment.js`
- [Security](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/routes/middleware.js): middleware · Request validation, auth checks, and service hardening. · `apps/backend/routes/middleware.js`
- [Query service](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/utils/queryExecutor.js): query orchestration · Generates, inspects, and executes MongoDB queries. · `apps/backend/utils/queryExecutor.js`
- [DB manager](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/utils/databaseManager.js): connection layer · Manages user database connections and schema access. · `apps/backend/utils/databaseManager.js`
- [AI helper](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/utils/geminiApi.js): genai · Gemini-assisted natural language to MongoDB query generation. · `apps/backend/utils/geminiApi.js`
- [Payment core](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/utils/PaymentHelper.js): payments · Payment helper logic and Cashfree integration. · `apps/backend/utils/PaymentHelper.js`
- [Mail service](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/utils/mailer.js): notifications · Transactional email for verification, resets, and alerts. · `apps/backend/utils/mailer.js`
- [Data models](https://github.com/himavarshithreddy/mongosnap/blob/main/apps/backend/models/User.js): mongoose models · User, connection, query, usage, token, and support records. · `apps/backend/models/User.js`

### Integrations

Third-party services and infrastructure outside the repo.

- **MongoDB Atlas**: datastore · Primary persistence for accounts, operational state, and records.
- **Gemini**: external ai · External AI service used for query generation.
- **Cashfree**: payment gateway · External payment processor for premium access.
- **SMTP/Brevo**: email service · External email delivery for transactional notifications.
- **GitHub Actions**: ci service · Automated deployment workflow for the monorepo.

## Connections

- MongoSnap → Workspace: defines · Workspace configuration ties the apps together.
- MongoSnap → Deploy: automates · Deployment is driven by workflow and script.
- MongoSnap → Client app: contains · Frontend lives under apps/frontend.
- MongoSnap → API app: contains · Backend lives under apps/backend.
- Deploy → GitHub Actions: runs on · GitHub Actions executes deploy workflow.
- Client app → Public shell: renders · Public pages and shared layout.
- Client app → Auth state: tracks session · Client auth state and protected routing.
- Client app → Playground: drives · Main product workflow for queries and schema browsing.
- Client app → Admin support: exposes · Support and moderation surfaces.
- Client app → Billing UI: handles · Upgrade and payment screens.
- Client app → Policy pages: shows · Policy content rendered in the client.
- Client app → API app: calls api · Authenticated screens talk to the Express backend.
- API app → Auth routes: routes · Authentication and identity endpoints.
- API app → Domain routes: routes · Application and support endpoints.
- API app → Payments: routes · Billing and subscription endpoints.
- API app → Security: guards · Middleware enforces trust boundaries.
- API app → Query service: orchestrates · API delegates query work to service utilities.
- API app → DB manager: connects · Manages MongoDB connections and schema inspection.
- API app → AI helper: uses · AI prompt handling and generation.
- API app → Payment core: uses · Payment processing helpers.
- API app → Mail service: uses · Transactional notification delivery.
- API app → Data models: persists via · Mongoose models back application state.
- Query service → DB manager: depends on · Query execution needs connection management.
- Query service → AI helper: consults · Natural language to query generation.
- Payment core → Cashfree: integrates · Cashfree is the external payment gateway.
- Mail service → SMTP/Brevo: delivers via · SMTP/Brevo sends transactional email.
- Data models → MongoDB Atlas: stores in · Primary persistent datastore.
- DB manager → MongoDB Atlas: connects to · User database connections and operational records.
- AI helper → Gemini: calls · Gemini provides AI-assisted generation.