How divya-jain07/trace works
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: app.js Express app · submission.controller.js Analysis logic · App.jsx SPA shell · auth.controller.js Auth logic
Components 21
Frontend
React/Vite single-page application
- SPA shell · Top-level client application and route composition
frontend/src/App.jsx - Pages · Landing, login, signup, dashboard, and analysis screens
frontend/src/pages - UI components · Reusable editor, navbar, insights, and account controls
frontend/src/components - Auth state · Client session and user state
frontend/src/context/AuthContext.jsx - Theme state · UI theme management
frontend/src/context/ThemeContext.jsx - API client · Browser boundary for backend requests
frontend/src/utils/api.js
Backend
Express API, auth, analysis, and persistence
- Server entry · Node process startup
backend/src/index.js - Express app · Middleware and route wiring
backend/src/app.js - Mongo connection · Database connectivity setup
backend/src/config/db.js - Auth routes · Register, login, logout, refresh, and password change endpoints
backend/src/routes/auth.routes.js - Auth logic · Session and credential operations
backend/src/controllers/auth.controller.js - Auth guard · JWT verification and protected access
backend/src/middlewares/auth.middleware.js - Submission routes · Code analysis endpoints for guest and authenticated users
backend/src/routes/submission.routes.js - Analysis logic · Submission lifecycle, status, and result handling
backend/src/controllers/submission.controller.js - Dashboard routes · Personal history and insights endpoints
backend/src/routes/dashboard.routes.js - Dashboard logic · Aggregated submission history and insights
backend/src/controllers/dashboard.controller.js - Gemini service · Wraps Google Gemini analysis generation
backend/src/services/gemini.service.js - User model · Accounts and auth-related records
backend/src/models/User.model.js - Submission model · Code submissions, analysis output, status, and hint history
backend/src/models/Submissions.model.js - API utils · Async handling and response envelope helpers
backend/src/utils
External
Third-party services
- Google Gemini · Third-party analysis engine
Connections 25
- 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