# rsayyed591/ai-dev-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/rsayyed591/ai-dev-assistant
- Repository: https://github.com/rsayyed591/ai-dev-assistant

## Overview

1. This repository is a two-part monorepo: a Next.js frontend in `ai-dev-assistant-frontend` and an Express/MongoDB backend in `ai-dev-assistant-backend`. The frontend is the user-facing shell; the backend owns authentication, AI calls, persistence, and request policy.

2. The frontend uses the Next.js App Router structure (`app/page.tsx`, `app/commit/page.tsx`, `app/rephrase/page.tsx`, `app/history/page.tsx`, `app/profile/page.tsx`). That suggests five main screens: landing, commit generation, text rephrasing, history, and profile. `components/AuthModal.tsx` is the key shared UI boundary for sign-in/sign-up.

3. The backend is organized in a standard layered Express shape: `routes` define HTTP endpoints, `controllers` handle request/response logic, `middleware` enforces auth and rate limits, `services` isolate the Groq LLM integration, `models` define MongoDB data structures, and `utils/prompts.js` centralizes prompt templates. This clean separation is the main architectural boundary in the API.

4. Authentication is JWT-based. `auth.controller.js` and `auth.route.js` handle register/login, `auth.middleware.js` protects AI and user routes, and the frontend likely stores and forwards the token for protected requests. The API design assumes all AI features are unavailable until the user is authenticated.

5. The primary business flows are two AI generation paths: rephrasing and commit message generation. `/api/rephrase` and `/api/commit` likely accept user text plus tone/context, pass that input through prompt builders in `utils/prompts.js`, call the Groq service in `services/groq.service.js`, and return a cleaned-up natural-language result.

6. History tracking is a separate user-centric subsystem exposed via `/api/history`. Because the backend tree only includes `user.model.js` and no dedicated history model, the last-10-request history is likely stored on the user document itself rather than in a standalone collection. That makes history a bounded per-user record, not an application-wide audit log.

7. The profile subsystem (`/api/profile`) is the read side of user state. It probably returns account metadata plus usage-related data that the frontend profile page can display. This sits alongside history as the “account data” boundary, distinct from the AI generation endpoints.

8. Rate limiting is enforced in backend middleware (`rateLimit.middleware.js`) and is described as per user/IP. Architecturally, that means request throttling sits in front of the AI endpoints to protect the Groq integration and control abuse, while remaining independent from business logic.

9. Persistence is MongoDB via Mongoose, configured in `src/config/db.js`. The only visible model is `user.model.js`, so user identity, auth-related fields, and any stored history are probably the core persisted state. No separate cache, job queue, or analytics store is present in the tree.

10. The backend also has a `vercel.json` and a top-level `api/index.js`, indicating it is deployable as a serverless-compatible Express API on Vercel. That deployment boundary matters because the backend is not just a local Node server; it is packaged to run behind a serverless platform while still exposing the same route structure.

11. The external dependency with the biggest architectural impact is Groq’s LLM API. The backend is effectively a thin orchestration layer between authenticated user input, prompt templates, and the model response. This keeps prompt logic centralized and prevents the frontend from ever talking directly to the LLM provider.

12. Overall data flow is: user interacts with the Next.js pages → frontend sends authenticated requests to Express endpoints → middleware checks JWT and rate limits → controllers validate/shape input → prompt utilities and Groq service generate output → MongoDB stores user/history state → response returns to the UI. The main boundaries are UI, API/auth policy, LLM orchestration, and persistence.

Main entry points: [`ai-dev-assistant-backend/src/app.js`](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/app.js) (App bootstrap), [`ai-dev-assistant-backend/src/controllers/commit.controller.js`](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/controllers/commit.controller.js) (Commit controller), [`ai-dev-assistant-backend/src/controllers/rephrase.controller.js`](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/controllers/rephrase.controller.js) (Rephrase controller), [`ai-dev-assistant-frontend/app/layout.tsx`](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/app/layout.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_shell["App shell<br/>Next.js app<br/>[layout.tsx]"]
  node_frontend_home["Landing<br/>screen<br/>[page.tsx]"]
  node_frontend_commit["Commit UI<br/>screen<br/>[page.tsx]"]
  node_frontend_rephrase["Rephrase UI<br/>screen<br/>[page.tsx]"]
  node_frontend_history["History UI<br/>screen<br/>[page.tsx]"]
  node_frontend_profile["Profile UI<br/>screen<br/>[page.tsx]"]
  node_frontend_auth["Auth modal<br/>shared ui<br/>[AuthModal.tsx]"]
end

subgraph group_backend["Backend"]
  node_api_entry["API entry<br/>serverless entry<br/>[index.js]"]
  node_app_boot["App bootstrap<br/>express app<br/>[app.js]"]
  node_db_config[("Mongo config<br/>db config<br/>[db.js]")]
  node_auth_routes["Auth routes<br/>[auth.route.js]"]
  node_ai_routes["AI routes<br/>[commit.route.js]"]
  node_history_route["History route<br/>[history.route.js]"]
  node_profile_route["Profile route<br/>[profile.route.js]"]
  node_auth_guard["Auth guard<br/>middleware<br/>[auth.middleware.js]"]
  node_rate_limit["Rate limit<br/>middleware"]
  node_user_model[("User model<br/>mongoose model<br/>[user.model.js]")]
  node_auth_ctrl["Auth controller<br/>[auth.controller.js]"]
  node_commit_ctrl["Commit controller"]
  node_rephrase_ctrl["Rephrase controller"]
  node_history_ctrl["History controller"]
  node_profile_ctrl["Profile controller"]
end

subgraph group_backend_ai["AI Orchestration"]
  node_prompts["Prompt utils<br/>prompt builder<br/>[prompts.js]"]
  node_groq_service["Groq service<br/>llm client<br/>[groq.service.js]"]
end

node_frontend_shell -->|"hosts"| node_frontend_home
node_frontend_shell -->|"routes to"| node_frontend_commit
node_frontend_shell -->|"routes to"| node_frontend_rephrase
node_frontend_shell -->|"routes to"| node_frontend_history
node_frontend_shell -->|"routes to"| node_frontend_profile
node_frontend_auth -->|"auths"| node_frontend_home
node_frontend_auth -->|"auths"| node_frontend_commit
node_frontend_auth -->|"auths"| node_frontend_rephrase
node_api_entry -->|"boots"| node_app_boot
node_app_boot -->|"mounts"| node_auth_routes
node_app_boot -->|"mounts"| node_ai_routes
node_app_boot -->|"mounts"| node_history_route
node_app_boot -->|"mounts"| node_profile_route
node_app_boot -->|"connects"| node_db_config
node_auth_routes -->|"handles"| node_auth_ctrl
node_ai_routes -->|"handles"| node_commit_ctrl
node_ai_routes -->|"handles"| node_rephrase_ctrl
node_history_route -->|"handles"| node_history_ctrl
node_profile_route -->|"handles"| node_profile_ctrl
node_auth_ctrl -->|"uses"| node_auth_guard
node_commit_ctrl -->|"protected by"| node_auth_guard
node_rephrase_ctrl -->|"protected by"| node_auth_guard
node_history_ctrl -->|"protected by"| node_auth_guard
node_profile_ctrl -->|"protected by"| node_auth_guard
node_commit_ctrl -->|"throttled by"| node_rate_limit
node_rephrase_ctrl -->|"throttled by"| node_rate_limit
node_commit_ctrl -->|"builds prompt"| node_prompts
node_rephrase_ctrl -->|"builds prompt"| node_prompts
node_prompts -->|"drives"| node_groq_service
node_commit_ctrl -->|"calls"| node_groq_service
node_rephrase_ctrl -->|"calls"| node_groq_service
node_history_ctrl -->|"reads"| node_user_model
node_profile_ctrl -->|"reads"| node_user_model
node_auth_ctrl -->|"writes"| node_user_model
node_commit_ctrl -->|"updates"| node_user_model
node_rephrase_ctrl -->|"updates"| node_user_model

click node_frontend_shell "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/app/layout.tsx"
click node_frontend_home "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/app/page.tsx"
click node_frontend_commit "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/app/commit/page.tsx"
click node_frontend_rephrase "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/app/rephrase/page.tsx"
click node_frontend_history "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/app/history/page.tsx"
click node_frontend_profile "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/app/profile/page.tsx"
click node_frontend_auth "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/components/AuthModal.tsx"
click node_api_entry "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/api/index.js"
click node_app_boot "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/app.js"
click node_db_config "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/config/db.js"
click node_auth_routes "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/routes/auth.route.js"
click node_ai_routes "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/routes/commit.route.js"
click node_history_route "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/routes/history.route.js"
click node_profile_route "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/routes/profile.route.js"
click node_auth_guard "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/middleware/auth.middleware.js"
click node_rate_limit "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/middleware/rateLimit.middleware.js"
click node_user_model "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/models/user.model.js"
click node_auth_ctrl "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/controllers/auth.controller.js"
click node_commit_ctrl "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/controllers/commit.controller.js"
click node_rephrase_ctrl "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/controllers/rephrase.controller.js"
click node_history_ctrl "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/controllers/history.controller.js"
click node_profile_ctrl "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/controllers/profile.controller.js"
click node_prompts "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/utils/prompts.js"
click node_groq_service "https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/services/groq.service.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_frontend_shell,node_frontend_home,node_frontend_commit,node_frontend_rephrase,node_frontend_history,node_frontend_profile,node_frontend_auth toneBlue
class node_api_entry,node_app_boot,node_db_config,node_auth_routes,node_ai_routes,node_history_route,node_profile_route,node_auth_guard,node_rate_limit,node_user_model,node_auth_ctrl,node_commit_ctrl,node_rephrase_ctrl,node_history_ctrl,node_profile_ctrl toneAmber
class node_prompts,node_groq_service toneMint
```

## Components

### Frontend

Next.js App Router UI for the assistant

- [App shell](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/app/layout.tsx): Next.js app · Global layout and landing entry for the client app · `ai-dev-assistant-frontend/app/layout.tsx`
- [Landing](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/app/page.tsx): screen · Main entry screen for the assistant · `ai-dev-assistant-frontend/app/page.tsx`
- [Commit UI](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/app/commit/page.tsx): screen · Commit message generation screen · `ai-dev-assistant-frontend/app/commit/page.tsx`
- [Rephrase UI](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/app/rephrase/page.tsx): screen · Text rephrasing screen · `ai-dev-assistant-frontend/app/rephrase/page.tsx`
- [History UI](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/app/history/page.tsx): screen · User history screen · `ai-dev-assistant-frontend/app/history/page.tsx`
- [Profile UI](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/app/profile/page.tsx): screen · User profile screen · `ai-dev-assistant-frontend/app/profile/page.tsx`
- [Auth modal](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-frontend/components/AuthModal.tsx): shared ui · Shared sign-in and sign-up boundary · `ai-dev-assistant-frontend/components/AuthModal.tsx`

### Backend

Express API, policy, and persistence

- [API entry](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/api/index.js): serverless entry · Vercel-compatible backend bootstrap · `ai-dev-assistant-backend/api/index.js`
- [App bootstrap](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/app.js): express app · Express application wiring and route registration · `ai-dev-assistant-backend/src/app.js`
- [Mongo config](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/config/db.js): db config · MongoDB connection setup · `ai-dev-assistant-backend/src/config/db.js`
- [Auth routes](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/routes/auth.route.js): route · Register and login endpoints · `ai-dev-assistant-backend/src/routes/auth.route.js`
- [AI routes](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/routes/commit.route.js): route · Commit and rephrase HTTP endpoints · `ai-dev-assistant-backend/src/routes/commit.route.js`
- [History route](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/routes/history.route.js): route · User history endpoint · `ai-dev-assistant-backend/src/routes/history.route.js`
- [Profile route](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/routes/profile.route.js): route · User profile endpoint · `ai-dev-assistant-backend/src/routes/profile.route.js`
- [Auth guard](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/middleware/auth.middleware.js): middleware · JWT protection for private endpoints · `ai-dev-assistant-backend/src/middleware/auth.middleware.js`
- [Rate limit](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/middleware/rateLimit.middleware.js): middleware · Per-user and per-IP request throttling · `ai-dev-assistant-backend/src/middleware/rateLimit.middleware.js`
- [User model](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/models/user.model.js): mongoose model · Core persisted user state and stored history · `ai-dev-assistant-backend/src/models/user.model.js`
- [Auth controller](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/controllers/auth.controller.js): controller · Login and registration request logic · `ai-dev-assistant-backend/src/controllers/auth.controller.js`
- [Commit controller](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/controllers/commit.controller.js): controller · Commit generation request logic · `ai-dev-assistant-backend/src/controllers/commit.controller.js`
- [Rephrase controller](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/controllers/rephrase.controller.js): controller · Rephrase generation request logic · `ai-dev-assistant-backend/src/controllers/rephrase.controller.js`
- [History controller](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/controllers/history.controller.js): controller · Reads per-user request history · `ai-dev-assistant-backend/src/controllers/history.controller.js`
- [Profile controller](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/controllers/profile.controller.js): controller · Reads account and usage data · `ai-dev-assistant-backend/src/controllers/profile.controller.js`

### AI Orchestration

Prompting and model integration inside the API

- [Prompt utils](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/utils/prompts.js): prompt builder · Centralized prompt templates and shaping · `ai-dev-assistant-backend/src/utils/prompts.js`
- [Groq service](https://github.com/rsayyed591/ai-dev-assistant/blob/main/ai-dev-assistant-backend/src/services/groq.service.js): llm client · Model API integration and response handling · `ai-dev-assistant-backend/src/services/groq.service.js`

## Connections

- App shell → Landing: hosts · The app shell contains the primary landing route
- App shell → Commit UI: routes to · Shell provides navigation to commit generation
- App shell → Rephrase UI: routes to · Shell provides navigation to rephrase generation
- App shell → History UI: routes to · Shell provides navigation to history
- App shell → Profile UI: routes to · Shell provides navigation to profile
- Auth modal → Landing: auths · Landing UI uses the shared auth modal
- Auth modal → Commit UI: auths · Protected generation flows rely on the shared auth modal
- Auth modal → Rephrase UI: auths · Protected generation flows rely on the shared auth modal
- API entry → App bootstrap: boots · Serverless entry initializes the Express app
- App bootstrap → Auth routes: mounts · Registers authentication endpoints
- App bootstrap → AI routes: mounts · Registers commit and rephrase endpoints
- App bootstrap → History route: mounts · Registers history endpoints
- App bootstrap → Profile route: mounts · Registers profile endpoints
- App bootstrap → Mongo config: connects · App startup connects to MongoDB
- Auth routes → Auth controller: handles · Auth routes delegate to controller logic
- AI routes → Commit controller: handles · Commit route delegates to commit controller
- AI routes → Rephrase controller: handles · Rephrase route delegates to rephrase controller
- History route → History controller: handles · History route delegates to history controller
- Profile route → Profile controller: handles · Profile route delegates to profile controller
- Auth controller → Auth guard: uses · Auth logic is coupled to JWT policy
- Commit controller → Auth guard: protected by · Commit generation requires authenticated access
- Rephrase controller → Auth guard: protected by · Rephrase generation requires authenticated access
- History controller → Auth guard: protected by · History access requires authenticated access
- Profile controller → Auth guard: protected by · Profile access requires authenticated access
- Commit controller → Rate limit: throttled by · AI generation is rate limited before execution
- Rephrase controller → Rate limit: throttled by · AI generation is rate limited before execution
- Commit controller → Prompt utils: builds prompt · Commit generation uses shared prompt templates
- Rephrase controller → Prompt utils: builds prompt · Rephrase generation uses shared prompt templates
- Prompt utils → Groq service: drives · Prompt output is sent to the LLM client
- Commit controller → Groq service: calls · Commit generation executes through the Groq client
- Rephrase controller → Groq service: calls · Rephrase generation executes through the Groq client
- History controller → User model: reads · History is stored on the user document
- Profile controller → User model: reads · Profile data comes from persisted user state
- Auth controller → User model: writes · Registration and login depend on user persistence
- Commit controller → User model: updates · Generation flow can append user history
- Rephrase controller → User model: updates · Generation flow can append user history