# krisna-codes37/devtrace architecture

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

- Interactive diagram: https://gitdiagram.com/krisna-codes37/devtrace
- Repository: https://github.com/krisna-codes37/devtrace

## Overview

DevTrace is a debugging-journal web application. A developer signs in, creates and searches a debugging session, records hypotheses and experiments with evidence, then captures root cause, solution, and lessons; session details present the journey as a timeline and can request AI analysis. The client uses React Query hooks and Axios to call an Express API, which validates and authorizes requests before operating on MongoDB-backed records. Dashboard statistics and Gemini analysis are additional capabilities. Some client and backend modules were not sampled; those links are included only where the README or SOURCE INDEX supports them.

Main entry points: [`server/src/app.js`](https://github.com/krisna-codes37/devtrace/blob/main/server/src/app.js) (Express API), [`client/src/App.jsx`](https://github.com/krisna-codes37/devtrace/blob/main/client/src/App.jsx) (App routes), [`server/src/controllers/ai.controller.js`](https://github.com/krisna-codes37/devtrace/blob/main/server/src/controllers/ai.controller.js) (Analysis controller), [`server/src/models/DebugSession.js`](https://github.com/krisna-codes37/devtrace/blob/main/server/src/models/DebugSession.js) (Debug sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["App routes<br/>[App.jsx]"]
  node_authui["Auth screens<br/>[LoginPage.jsx]"]
  node_sessionsui["Session browser<br/>[SessionsPage.jsx]"]
  node_sessionform["Session form<br/>[SessionForm.jsx]"]
  node_details["Session details"]
  node_timeline["Journey timeline"]
  node_hypothesisui["Hypothesis section"]
  node_queryhooks["Session queries<br/>[useSessions.js]"]
  node_http["API client<br/>[client.js]"]
  node_sessionapi["Session API<br/>[sessions.js]"]
end

subgraph group_journey["Investigation records"]
  node_model_session[("Debug sessions<br/>[DebugSession.js]")]
  node_model_hypothesis[("Hypotheses<br/>[Hypothesis.js]")]
  node_model_experiment[("Experiments<br/>[Experiment.js]")]
  node_sessionctrl["Session operations"]
  node_hypctrl["Hypothesis operations"]
  node_expctrl["Experiment operations"]
end

subgraph group_identity["Identity and API"]
  node_server["Express API<br/>[app.js]"]
  node_sessionroutes["Session routes<br/>[session.routes.js]"]
  node_hyproutes["Hypothesis routes"]
  node_exproutes["Experiment routes"]
  node_authroutes["Auth routes<br/>[auth.routes.js]"]
  node_authctrl["Account operations<br/>[auth.controller.js]"]
  node_authmw["JWT authorization<br/>[auth.js]"]
  node_user[("User records<br/>[User.js]")]
  node_validation["Request validation<br/>[validate.js]"]
end

subgraph group_insights["Insights and integrations"]
  node_dashboard["Dashboard statistics"]
  node_aiui["AI analysis action<br/>[ai.js]"]
  node_aictrl["Analysis controller<br/>[ai.controller.js]"]
  node_gemini["Gemini service<br/>[gemini.js]"]
  node_geminisvc["Gemini API"]
end

node_developer(("Developer"))

node_developer -->|"uses"| node_app
node_app -->|"routes to"| node_authui
node_app -->|"routes to"| node_sessionsui
node_app -->|"routes to"| node_sessionform
node_app -->|"routes to"| node_details
node_sessionsui -->|"queries"| node_queryhooks
node_queryhooks -->|"calls"| node_sessionapi
node_sessionform -.->|"submits"| node_sessionapi
node_details -->|"loads"| node_timeline
node_details -->|"renders"| node_hypothesisui
node_http -->|"sends JSON"| node_server
node_sessionapi -->|"uses"| node_http
node_server -->|"mounts"| node_sessionroutes
node_server -->|"mounts"| node_hyproutes
node_server -->|"mounts"| node_exproutes
node_server -->|"mounts"| node_authroutes
node_sessionroutes -->|"dispatches"| node_sessionctrl
node_hyproutes -->|"dispatches"| node_hypctrl
node_exproutes -->|"dispatches"| node_expctrl
node_authroutes -->|"dispatches"| node_authctrl
node_sessionroutes -->|"validates"| node_validation
node_hyproutes -->|"validates"| node_validation
node_exproutes -->|"validates"| node_validation
node_sessionroutes -->|"requires"| node_authmw
node_authroutes -->|"requires"| node_authmw
node_authmw -->|"loads user"| node_user
node_authctrl -->|"manages"| node_user
node_sessionctrl -->|"queries"| node_model_session
node_sessionctrl -->|"deletes children"| node_model_experiment
node_sessionctrl -->|"deletes children"| node_model_hypothesis
node_hypctrl -->|"checks ownership"| node_model_session
node_hypctrl -->|"manages"| node_model_hypothesis
node_expctrl -->|"checks parent"| node_model_hypothesis
node_expctrl -->|"checks ownership"| node_model_session
node_expctrl -->|"manages"| node_model_experiment
node_dashboard -.->|"aggregates"| node_model_session
node_details -->|"requests analysis"| node_aiui
node_aiui -->|"posts analysis"| node_server
node_server -->|"routes analysis"| node_aictrl
node_aictrl -->|"reads investigation"| node_model_session
node_aictrl -->|"reads investigation"| node_model_hypothesis
node_aictrl -->|"reads investigation"| node_model_experiment
node_aictrl -->|"requests insights"| node_gemini
node_gemini -.->|"calls"| node_geminisvc

click node_app "https://github.com/krisna-codes37/devtrace/blob/main/client/src/App.jsx"
click node_authui "https://github.com/krisna-codes37/devtrace/blob/main/client/src/pages/LoginPage.jsx"
click node_sessionsui "https://github.com/krisna-codes37/devtrace/blob/main/client/src/pages/SessionsPage.jsx"
click node_sessionform "https://github.com/krisna-codes37/devtrace/blob/main/client/src/components/SessionForm.jsx"
click node_details "https://github.com/krisna-codes37/devtrace/blob/main/client/src/pages/SessionDetailsPage.jsx"
click node_timeline "https://github.com/krisna-codes37/devtrace/blob/main/client/src/hooks/useJourneyTimeline.js"
click node_hypothesisui "https://github.com/krisna-codes37/devtrace/blob/main/client/src/components/HypothesisSection.jsx"
click node_queryhooks "https://github.com/krisna-codes37/devtrace/blob/main/client/src/hooks/useSessions.js"
click node_http "https://github.com/krisna-codes37/devtrace/blob/main/client/src/api/client.js"
click node_sessionapi "https://github.com/krisna-codes37/devtrace/blob/main/client/src/api/sessions.js"
click node_model_session "https://github.com/krisna-codes37/devtrace/blob/main/server/src/models/DebugSession.js"
click node_model_hypothesis "https://github.com/krisna-codes37/devtrace/blob/main/server/src/models/Hypothesis.js"
click node_model_experiment "https://github.com/krisna-codes37/devtrace/blob/main/server/src/models/Experiment.js"
click node_sessionctrl "https://github.com/krisna-codes37/devtrace/blob/main/server/src/controllers/session.controller.js"
click node_hypctrl "https://github.com/krisna-codes37/devtrace/blob/main/server/src/controllers/hypothesis.controller.js"
click node_expctrl "https://github.com/krisna-codes37/devtrace/blob/main/server/src/controllers/experiment.controller.js"
click node_server "https://github.com/krisna-codes37/devtrace/blob/main/server/src/app.js"
click node_sessionroutes "https://github.com/krisna-codes37/devtrace/blob/main/server/src/routes/session.routes.js"
click node_hyproutes "https://github.com/krisna-codes37/devtrace/blob/main/server/src/routes/hypothesis.routes.js"
click node_exproutes "https://github.com/krisna-codes37/devtrace/blob/main/server/src/routes/experiment.routes.js"
click node_authroutes "https://github.com/krisna-codes37/devtrace/blob/main/server/src/routes/auth.routes.js"
click node_authctrl "https://github.com/krisna-codes37/devtrace/blob/main/server/src/controllers/auth.controller.js"
click node_authmw "https://github.com/krisna-codes37/devtrace/blob/main/server/src/middleware/auth.js"
click node_user "https://github.com/krisna-codes37/devtrace/blob/main/server/src/models/User.js"
click node_validation "https://github.com/krisna-codes37/devtrace/blob/main/server/src/middleware/validate.js"
click node_dashboard "https://github.com/krisna-codes37/devtrace/blob/main/server/src/controllers/dashboard.controller.js"
click node_aiui "https://github.com/krisna-codes37/devtrace/blob/main/client/src/api/ai.js"
click node_aictrl "https://github.com/krisna-codes37/devtrace/blob/main/server/src/controllers/ai.controller.js"
click node_gemini "https://github.com/krisna-codes37/devtrace/blob/main/server/src/services/ai/gemini.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_app,node_authui,node_sessionsui,node_sessionform,node_details,node_timeline,node_hypothesisui,node_queryhooks,node_http,node_sessionapi toneBlue
class node_model_session,node_model_hypothesis,node_model_experiment,node_sessionctrl,node_hypctrl,node_expctrl toneAmber
class node_server,node_sessionroutes,node_hyproutes,node_exproutes,node_authroutes,node_authctrl,node_authmw,node_user,node_validation toneMint
class node_dashboard,node_aiui,node_aictrl,node_gemini,node_geminisvc toneRose
class node_developer toneIndigo
```

## Components

### Client experience

- [App routes](https://github.com/krisna-codes37/devtrace/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Auth screens](https://github.com/krisna-codes37/devtrace/blob/main/client/src/pages/LoginPage.jsx): `client/src/pages/LoginPage.jsx`
- [Session browser](https://github.com/krisna-codes37/devtrace/blob/main/client/src/pages/SessionsPage.jsx): `client/src/pages/SessionsPage.jsx`
- [Session form](https://github.com/krisna-codes37/devtrace/blob/main/client/src/components/SessionForm.jsx): `client/src/components/SessionForm.jsx`
- [Session details](https://github.com/krisna-codes37/devtrace/blob/main/client/src/pages/SessionDetailsPage.jsx): `client/src/pages/SessionDetailsPage.jsx`
- [Journey timeline](https://github.com/krisna-codes37/devtrace/blob/main/client/src/hooks/useJourneyTimeline.js): `client/src/hooks/useJourneyTimeline.js`
- [Hypothesis section](https://github.com/krisna-codes37/devtrace/blob/main/client/src/components/HypothesisSection.jsx): `client/src/components/HypothesisSection.jsx`
- [Session queries](https://github.com/krisna-codes37/devtrace/blob/main/client/src/hooks/useSessions.js): `client/src/hooks/useSessions.js`
- [API client](https://github.com/krisna-codes37/devtrace/blob/main/client/src/api/client.js): `client/src/api/client.js`
- [Session API](https://github.com/krisna-codes37/devtrace/blob/main/client/src/api/sessions.js): `client/src/api/sessions.js`

### Investigation records

- [Debug sessions](https://github.com/krisna-codes37/devtrace/blob/main/server/src/models/DebugSession.js): `server/src/models/DebugSession.js`
- [Hypotheses](https://github.com/krisna-codes37/devtrace/blob/main/server/src/models/Hypothesis.js): `server/src/models/Hypothesis.js`
- [Experiments](https://github.com/krisna-codes37/devtrace/blob/main/server/src/models/Experiment.js): `server/src/models/Experiment.js`
- [Session operations](https://github.com/krisna-codes37/devtrace/blob/main/server/src/controllers/session.controller.js): `server/src/controllers/session.controller.js`
- [Hypothesis operations](https://github.com/krisna-codes37/devtrace/blob/main/server/src/controllers/hypothesis.controller.js): `server/src/controllers/hypothesis.controller.js`
- [Experiment operations](https://github.com/krisna-codes37/devtrace/blob/main/server/src/controllers/experiment.controller.js): `server/src/controllers/experiment.controller.js`

### Identity and API

- [Express API](https://github.com/krisna-codes37/devtrace/blob/main/server/src/app.js): `server/src/app.js`
- [Session routes](https://github.com/krisna-codes37/devtrace/blob/main/server/src/routes/session.routes.js): `server/src/routes/session.routes.js`
- [Hypothesis routes](https://github.com/krisna-codes37/devtrace/blob/main/server/src/routes/hypothesis.routes.js): `server/src/routes/hypothesis.routes.js`
- [Experiment routes](https://github.com/krisna-codes37/devtrace/blob/main/server/src/routes/experiment.routes.js): `server/src/routes/experiment.routes.js`
- [Auth routes](https://github.com/krisna-codes37/devtrace/blob/main/server/src/routes/auth.routes.js): `server/src/routes/auth.routes.js`
- [Account operations](https://github.com/krisna-codes37/devtrace/blob/main/server/src/controllers/auth.controller.js): `server/src/controllers/auth.controller.js`
- [JWT authorization](https://github.com/krisna-codes37/devtrace/blob/main/server/src/middleware/auth.js): `server/src/middleware/auth.js`
- [User records](https://github.com/krisna-codes37/devtrace/blob/main/server/src/models/User.js): `server/src/models/User.js`
- [Request validation](https://github.com/krisna-codes37/devtrace/blob/main/server/src/middleware/validate.js): `server/src/middleware/validate.js`

### Insights and integrations

- [Dashboard statistics](https://github.com/krisna-codes37/devtrace/blob/main/server/src/controllers/dashboard.controller.js): `server/src/controllers/dashboard.controller.js`
- [AI analysis action](https://github.com/krisna-codes37/devtrace/blob/main/client/src/api/ai.js): `client/src/api/ai.js`
- [Analysis controller](https://github.com/krisna-codes37/devtrace/blob/main/server/src/controllers/ai.controller.js): `server/src/controllers/ai.controller.js`
- [Gemini service](https://github.com/krisna-codes37/devtrace/blob/main/server/src/services/ai/gemini.js): `server/src/services/ai/gemini.js`
- **Gemini API**

### Other components

- **Developer**

## Connections

- Developer → App routes: uses (evidence: `README.md`)
- App routes → Auth screens: routes to (evidence: `client/src/App.jsx`)
- App routes → Session browser: routes to (evidence: `client/src/App.jsx`)
- App routes → Session form: routes to (evidence: `client/src/App.jsx`)
- App routes → Session details: routes to (evidence: `client/src/App.jsx`)
- Session browser → Session queries: queries (evidence: `client/src/pages/SessionsPage.jsx`)
- Session queries → Session API: calls (evidence: `client/src/hooks/useSessions.js`)
- Session form → Session API: submits (evidence: `README.md`)
- Session details → Journey timeline: loads (evidence: `client/src/pages/SessionDetailsPage.jsx`)
- Session details → Hypothesis section: renders (evidence: `client/src/pages/SessionDetailsPage.jsx`)
- API client → Express API: sends JSON (evidence: `README.md`)
- Session API → API client: uses (evidence: `client/src/api/sessions.js`)
- Express API → Session routes: mounts (evidence: `server/src/app.js`)
- Express API → Hypothesis routes: mounts (evidence: `server/src/app.js`)
- Express API → Experiment routes: mounts (evidence: `server/src/app.js`)
- Express API → Auth routes: mounts (evidence: `server/src/app.js`)
- Session routes → Session operations: dispatches (evidence: `server/src/routes/session.routes.js`)
- Hypothesis routes → Hypothesis operations: dispatches (evidence: `server/src/routes/hypothesis.routes.js`)
- Experiment routes → Experiment operations: dispatches (evidence: `server/src/routes/experiment.routes.js`)
- Auth routes → Account operations: dispatches (evidence: `server/src/routes/auth.routes.js`)
- Session routes → Request validation: validates (evidence: `server/src/routes/session.routes.js`)
- Hypothesis routes → Request validation: validates (evidence: `server/src/routes/hypothesis.routes.js`)
- Experiment routes → Request validation: validates (evidence: `server/src/routes/experiment.routes.js`)
- Session routes → JWT authorization: requires (evidence: `server/src/routes/session.routes.js`)
- Auth routes → JWT authorization: requires (evidence: `server/src/routes/auth.routes.js`)
- JWT authorization → User records: loads user (evidence: `server/src/middleware/auth.js`)
- Account operations → User records: manages (evidence: `server/src/controllers/auth.controller.js`)
- Session operations → Debug sessions: queries (evidence: `server/src/controllers/session.controller.js`)
- Session operations → Experiments: deletes children (evidence: `server/src/controllers/session.controller.js`)
- Session operations → Hypotheses: deletes children (evidence: `server/src/controllers/session.controller.js`)
- Hypothesis operations → Debug sessions: checks ownership (evidence: `server/src/controllers/hypothesis.controller.js`)
- Hypothesis operations → Hypotheses: manages (evidence: `server/src/controllers/hypothesis.controller.js`)
- Experiment operations → Hypotheses: checks parent (evidence: `server/src/controllers/experiment.controller.js`)
- Experiment operations → Debug sessions: checks ownership (evidence: `server/src/controllers/experiment.controller.js`)
- Experiment operations → Experiments: manages (evidence: `server/src/controllers/experiment.controller.js`)
- Dashboard statistics → Debug sessions: aggregates (evidence: `README.md`)
- Session details → AI analysis action: requests analysis (evidence: `client/src/pages/SessionDetailsPage.jsx`)
- AI analysis action → Express API: posts analysis (evidence: `README.md`)
- Express API → Analysis controller: routes analysis (evidence: `server/src/app.js`)
- Analysis controller → Debug sessions: reads investigation (evidence: `server/src/controllers/ai.controller.js`)
- Analysis controller → Hypotheses: reads investigation (evidence: `server/src/controllers/ai.controller.js`)
- Analysis controller → Experiments: reads investigation (evidence: `server/src/controllers/ai.controller.js`)
- Analysis controller → Gemini service: requests insights (evidence: `server/src/controllers/ai.controller.js`)
- Gemini service → Gemini API: calls (evidence: `README.md`)
