# divya-jain07/trace architecture

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

- Interactive diagram: https://gitdiagram.com/divya-jain07/trace
- Repository: https://github.com/divya-jain07/trace

## Overview

1. **Overall shape**
   - Trace is a two-tier full-stack app: a **React/Vite frontend** in `frontend/` and a **Node/Express backend** in `backend/`.
   - The architecture centers on a **code-submission analysis workflow** backed by **MongoDB** and powered by the **Google Gemini API**.

2. **Frontend boundary**
   - The frontend is a **single-page app** with route-level pages for `Landing`, `Login`, `Signup`, `Dashboard`, and `Analysis`.
   - UI composition is split into reusable components such as `CodeEditor`, `AnalysisInsights`, `RecentSubmissions`, `AppNavbar`, `ProfileDropdown`, and `ChangePasswordModal`.

3. **Frontend state and client concerns**
   - `AuthContext` holds user/session state, while `ThemeContext` manages UI theme.
   - `src/utils/api.js` is the client boundary to the backend, likely using Axios and cookie-based auth.
   - The UI includes a code entry flow, analysis display, dashboard history, and account controls rather than a generic page hierarchy.

4. **Backend bootstrap and infrastructure**
   - `src/index.js` is the server entrypoint and `src/app.js` is the Express application assembly point.
   - `src/config/db.js` owns the MongoDB connection.
   - Runtime behavior is driven by environment variables such as database URL, JWT secrets, token expiry, and the Gemini API key.

5. **Authentication subsystem**
   - Auth is separated into `auth.routes.js` and `auth.controller.js`, with JWT verification handled by `auth.middleware.js`.
   - The backend supports **register, login, logout, refresh token, and password change**.
   - The README indicates **access + refresh tokens in httpOnly cookies** and bcrypt password hashing, so session management is cookie-based rather than local-storage-based.

6. **Submission analysis pipeline**
   - `submission.routes.js` and `submission.controller.js` expose the main analysis workflow.
   - There are two entry paths: **guest analysis** and **authenticated analysis**.
   - The backend likely creates or updates a `Submission` record, sends the code to Gemini, stores the result, and exposes a status endpoint for later retrieval.

7. **AI/analysis service boundary**
   - `services/gemini.service.js` isolates the external LLM dependency from route/controller code.
   - This is the primary outbound integration in the system and is responsible for generating the mentoring-style analysis: complexity, style, approach quality, TLE risk, topics, and tiered hints.

8. **Persistence model**
   - `models/User.model.js` stores account and auth-related data.
   - `models/Submissions.model.js` stores code submissions, analysis output, status, and hint usage/history.
   - The database acts as both the **source of truth for user identity** and the **historical record for analyses**.

9. **Dashboard and insights**
   - `dashboard.routes.js` and `dashboard.controller.js` serve personal analytics.
   - The dashboard reads from submissions to provide **history** and **aggregated insights** across prior analyses.
   - This is a read-heavy view built on top of the submission store rather than a separate analytics database.

10. **Cross-cutting backend utilities**
   - `utils/asyncHandler.js` standardizes async route error handling.
   - `utils/ApiResponse.js` suggests a consistent API response envelope across endpoints.
   - These utilities keep controllers focused on business logic and response shape consistent for the frontend.

11. **Request/data flow**
   - Typical flow: user enters code in the frontend editor → frontend calls `/api/analyze` or `/api/analyze/guest` → backend authenticates if needed → Gemini analysis runs → result is persisted in MongoDB → frontend fetches status/result and then dashboard history/insights.
   - A separate auth flow handles sign-in/session refresh, which gates the dashboard and authenticated analysis.

12. **Important architectural boundaries for a diagram**
   - **Browser/SPA boundary**: React UI and client-side routing.
   - **API boundary**: Express routes grouped by auth, submissions, and dashboard.
   - **Data boundary**: MongoDB models for users and submissions.
   - **External service boundary**: Google Gemini for code review intelligence.
   - **Session boundary**: JWT cookies and middleware-protected routes.

Main entry points: [`backend/src/app.js`](https://github.com/divya-jain07/trace/blob/main/backend/src/app.js) (Express app), [`backend/src/controllers/submission.controller.js`](https://github.com/divya-jain07/trace/blob/main/backend/src/controllers/submission.controller.js) (Analysis logic), [`frontend/src/App.jsx`](https://github.com/divya-jain07/trace/blob/main/frontend/src/App.jsx) (SPA shell), [`backend/src/controllers/auth.controller.js`](https://github.com/divya-jain07/trace/blob/main/backend/src/controllers/auth.controller.js) (Auth logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["SPA shell<br/>React app<br/>[App.jsx]"]
  node_frontend_pages["Pages<br/>routes"]
  node_frontend_components["UI components<br/>shared UI"]
  node_frontend_auth_ctx(("Auth state<br/>context<br/>[AuthContext.jsx]"))
  node_frontend_theme_ctx(("Theme state<br/>context<br/>[ThemeContext.jsx]"))
  node_frontend_api["API client<br/>HTTP client<br/>[api.js]"]
end

subgraph group_backend["Backend"]
  node_backend_entry["Server entry<br/>bootstrap<br/>[index.js]"]
  node_backend_app["Express app<br/>app assembly<br/>[app.js]"]
  node_backend_db[("Mongo connection<br/>database config<br/>[db.js]")]
  node_backend_auth_routes["Auth routes<br/>[auth.routes.js]"]
  node_backend_auth_ctrl["Auth logic<br/>controller<br/>[auth.controller.js]"]
  node_backend_auth_mw{{"Auth guard<br/>middleware<br/>[auth.middleware.js]"}}
  node_backend_submission_routes["Submission routes"]
  node_backend_submission_ctrl["Analysis logic<br/>controller"]
  node_backend_dashboard_routes["Dashboard routes"]
  node_backend_dashboard_ctrl["Dashboard logic<br/>controller"]
  node_backend_gemini["Gemini service<br/>LLM adapter<br/>[gemini.service.js]"]
  node_backend_user_model[("User model<br/>Mongo model<br/>[User.model.js]")]
  node_backend_submission_model[("Submission model<br/>Mongo model")]
  node_backend_utils["API utils<br/>helpers"]
end

subgraph group_external["External"]
  node_external_gemini{{"Google Gemini<br/>external LLM"}}
end

node_frontend_app -->|"renders"| node_frontend_pages
node_frontend_app -->|"composes"| node_frontend_components
node_frontend_app -->|"uses"| node_frontend_auth_ctx
node_frontend_app -->|"uses"| node_frontend_theme_ctx
node_frontend_pages -->|"calls"| node_frontend_api
node_frontend_components -->|"calls"| node_frontend_api
node_frontend_api -->|"HTTP API"| node_backend_app
node_backend_entry -->|"starts"| node_backend_app
node_backend_app -->|"connects"| node_backend_db
node_backend_app -->|"mounts"| node_backend_auth_routes
node_backend_app -->|"mounts"| node_backend_submission_routes
node_backend_app -->|"mounts"| node_backend_dashboard_routes
node_backend_auth_routes -->|"delegates"| node_backend_auth_ctrl
node_backend_submission_routes -->|"delegates"| node_backend_submission_ctrl
node_backend_dashboard_routes -->|"delegates"| node_backend_dashboard_ctrl
node_backend_auth_ctrl -->|"protects"| node_backend_auth_mw
node_backend_auth_ctrl -->|"reads/writes"| node_backend_user_model
node_backend_submission_ctrl -->|"checks"| node_backend_auth_mw
node_backend_submission_ctrl -->|"reads/writes"| node_backend_submission_model
node_backend_submission_ctrl -->|"analyzes with"| node_backend_gemini
node_backend_dashboard_ctrl -->|"aggregates"| node_backend_submission_model
node_backend_gemini -->|"uses"| node_external_gemini
node_backend_auth_ctrl -->|"uses"| node_backend_utils
node_backend_submission_ctrl -->|"uses"| node_backend_utils
node_backend_dashboard_ctrl -->|"uses"| node_backend_utils

click node_frontend_app "https://github.com/divya-jain07/trace/blob/main/frontend/src/App.jsx"
click node_frontend_pages "https://github.com/divya-jain07/trace/tree/main/frontend/src/pages"
click node_frontend_components "https://github.com/divya-jain07/trace/tree/main/frontend/src/components"
click node_frontend_auth_ctx "https://github.com/divya-jain07/trace/blob/main/frontend/src/context/AuthContext.jsx"
click node_frontend_theme_ctx "https://github.com/divya-jain07/trace/blob/main/frontend/src/context/ThemeContext.jsx"
click node_frontend_api "https://github.com/divya-jain07/trace/blob/main/frontend/src/utils/api.js"
click node_backend_entry "https://github.com/divya-jain07/trace/blob/main/backend/src/index.js"
click node_backend_app "https://github.com/divya-jain07/trace/blob/main/backend/src/app.js"
click node_backend_db "https://github.com/divya-jain07/trace/blob/main/backend/src/config/db.js"
click node_backend_auth_routes "https://github.com/divya-jain07/trace/blob/main/backend/src/routes/auth.routes.js"
click node_backend_auth_ctrl "https://github.com/divya-jain07/trace/blob/main/backend/src/controllers/auth.controller.js"
click node_backend_auth_mw "https://github.com/divya-jain07/trace/blob/main/backend/src/middlewares/auth.middleware.js"
click node_backend_submission_routes "https://github.com/divya-jain07/trace/blob/main/backend/src/routes/submission.routes.js"
click node_backend_submission_ctrl "https://github.com/divya-jain07/trace/blob/main/backend/src/controllers/submission.controller.js"
click node_backend_dashboard_routes "https://github.com/divya-jain07/trace/blob/main/backend/src/routes/dashboard.routes.js"
click node_backend_dashboard_ctrl "https://github.com/divya-jain07/trace/blob/main/backend/src/controllers/dashboard.controller.js"
click node_backend_gemini "https://github.com/divya-jain07/trace/blob/main/backend/src/services/gemini.service.js"
click node_backend_user_model "https://github.com/divya-jain07/trace/blob/main/backend/src/models/User.model.js"
click node_backend_submission_model "https://github.com/divya-jain07/trace/blob/main/backend/src/models/Submissions.model.js"
click node_backend_utils "https://github.com/divya-jain07/trace/tree/main/backend/src/utils"

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_frontend_app,node_frontend_pages,node_frontend_components,node_frontend_auth_ctx,node_frontend_theme_ctx,node_frontend_api toneBlue
class node_backend_entry,node_backend_app,node_backend_db,node_backend_auth_routes,node_backend_auth_ctrl,node_backend_auth_mw,node_backend_submission_routes,node_backend_submission_ctrl,node_backend_dashboard_routes,node_backend_dashboard_ctrl,node_backend_gemini,node_backend_user_model,node_backend_submission_model,node_backend_utils toneAmber
class node_external_gemini toneMint
```

## Components

### Frontend

React/Vite single-page application

- [SPA shell](https://github.com/divya-jain07/trace/blob/main/frontend/src/App.jsx): React app · Top-level client application and route composition · `frontend/src/App.jsx`
- [Pages](https://github.com/divya-jain07/trace/tree/main/frontend/src/pages): routes · Landing, login, signup, dashboard, and analysis screens · `frontend/src/pages`
- [UI components](https://github.com/divya-jain07/trace/tree/main/frontend/src/components): shared UI · Reusable editor, navbar, insights, and account controls · `frontend/src/components`
- [Auth state](https://github.com/divya-jain07/trace/blob/main/frontend/src/context/AuthContext.jsx): context · Client session and user state · `frontend/src/context/AuthContext.jsx`
- [Theme state](https://github.com/divya-jain07/trace/blob/main/frontend/src/context/ThemeContext.jsx): context · UI theme management · `frontend/src/context/ThemeContext.jsx`
- [API client](https://github.com/divya-jain07/trace/blob/main/frontend/src/utils/api.js): HTTP client · Browser boundary for backend requests · `frontend/src/utils/api.js`

### Backend

Express API, auth, analysis, and persistence

- [Server entry](https://github.com/divya-jain07/trace/blob/main/backend/src/index.js): bootstrap · Node process startup · `backend/src/index.js`
- [Express app](https://github.com/divya-jain07/trace/blob/main/backend/src/app.js): app assembly · Middleware and route wiring · `backend/src/app.js`
- [Mongo connection](https://github.com/divya-jain07/trace/blob/main/backend/src/config/db.js): database config · Database connectivity setup · `backend/src/config/db.js`
- [Auth routes](https://github.com/divya-jain07/trace/blob/main/backend/src/routes/auth.routes.js): routes · Register, login, logout, refresh, and password change endpoints · `backend/src/routes/auth.routes.js`
- [Auth logic](https://github.com/divya-jain07/trace/blob/main/backend/src/controllers/auth.controller.js): controller · Session and credential operations · `backend/src/controllers/auth.controller.js`
- [Auth guard](https://github.com/divya-jain07/trace/blob/main/backend/src/middlewares/auth.middleware.js): middleware · JWT verification and protected access · `backend/src/middlewares/auth.middleware.js`
- [Submission routes](https://github.com/divya-jain07/trace/blob/main/backend/src/routes/submission.routes.js): routes · Code analysis endpoints for guest and authenticated users · `backend/src/routes/submission.routes.js`
- [Analysis logic](https://github.com/divya-jain07/trace/blob/main/backend/src/controllers/submission.controller.js): controller · Submission lifecycle, status, and result handling · `backend/src/controllers/submission.controller.js`
- [Dashboard routes](https://github.com/divya-jain07/trace/blob/main/backend/src/routes/dashboard.routes.js): routes · Personal history and insights endpoints · `backend/src/routes/dashboard.routes.js`
- [Dashboard logic](https://github.com/divya-jain07/trace/blob/main/backend/src/controllers/dashboard.controller.js): controller · Aggregated submission history and insights · `backend/src/controllers/dashboard.controller.js`
- [Gemini service](https://github.com/divya-jain07/trace/blob/main/backend/src/services/gemini.service.js): LLM adapter · Wraps Google Gemini analysis generation · `backend/src/services/gemini.service.js`
- [User model](https://github.com/divya-jain07/trace/blob/main/backend/src/models/User.model.js): Mongo model · Accounts and auth-related records · `backend/src/models/User.model.js`
- [Submission model](https://github.com/divya-jain07/trace/blob/main/backend/src/models/Submissions.model.js): Mongo model · Code submissions, analysis output, status, and hint history · `backend/src/models/Submissions.model.js`
- [API utils](https://github.com/divya-jain07/trace/tree/main/backend/src/utils): helpers · Async handling and response envelope helpers · `backend/src/utils`

### External

Third-party services

- **Google Gemini**: external LLM · Third-party analysis engine

## Connections

- SPA shell → Pages: renders · Route-level screens are mounted by the SPA
- SPA shell → UI components: composes · Pages and layouts reuse shared UI parts
- SPA shell → Auth state: uses · Client auth state is consumed across the app
- SPA shell → Theme state: uses · Theme toggling is available globally
- Pages → API client: calls · Screens submit auth and analysis requests
- UI components → API client: calls · Editor and dashboard components fetch backend data
- API client → Express app: HTTP API · Browser requests reach the Express backend
- Server entry → Express app: starts · Process bootstraps the Express application
- Express app → Mongo connection: connects · Application initializes MongoDB access
- Express app → Auth routes: mounts · Auth endpoints are registered on the app
- Express app → Submission routes: mounts · Submission analysis endpoints are registered on the app
- Express app → Dashboard routes: mounts · Dashboard endpoints are registered on the app
- Auth routes → Auth logic: delegates · Route handlers forward to auth business logic
- Submission routes → Analysis logic: delegates · Route handlers forward to analysis workflow logic
- Dashboard routes → Dashboard logic: delegates · Route handlers forward to dashboard aggregation logic
- Auth logic → Auth guard: protects · Session verification gates sensitive auth actions
- Auth logic → User model: reads/writes · User records are created and updated
- Analysis logic → Auth guard: checks · Authenticated analysis passes through JWT guard
- Analysis logic → Submission model: reads/writes · Submission state and results are persisted
- Analysis logic → Gemini service: analyzes with · Code is sent for mentoring-style review generation
- Dashboard logic → Submission model: aggregates · Dashboard derives history and insights from submissions
- Gemini service → Google Gemini: uses · Service adapter wraps the external LLM API
- Auth logic → API utils: uses · Responses and async errors are normalized
- Analysis logic → API utils: uses · Responses and async errors are normalized
- Dashboard logic → API utils: uses · Responses and async errors are normalized
