# jihedsaguer/neurostage_ai_backend architecture

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

- Interactive diagram: https://gitdiagram.com/jihedsaguer/neurostage_ai_backend
- Repository: https://github.com/jihedsaguer/neurostage_ai_backend

## Overview

The source tree describes a NestJS backend for internship and academic-placement management, with authentication, user profiles, applications, supervision, milestones, messaging, AI/RAG, analytics, and audit capabilities. The likely user workflow is authenticated access to those domain APIs; the tree alone does not establish a sequential application-to-placement process, so the graph keeps those stages as separate capabilities. Relationships are limited to calls or imports shown in excerpts and the SOURCE INDEX; several feature services were not sampled.

Main entry points: [`src/app.module.ts`](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/app.module.ts) (Nest application), [`src/modules/auth/auth.service.ts`](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/auth/auth.service.ts) (Authentication service), [`src/modules/auth/auth.controller.ts`](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/auth/auth.controller.ts) (Authentication API), [`src/modules/rag/rag.controller.ts`](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/rag/rag.controller.ts) (Procedure knowledge API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and identity"]
  node_auth_api["Authentication API<br/>[auth.controller.ts]"]
  node_auth_logic["Authentication service<br/>[auth.service.ts]"]
  node_user_data[("User records<br/>[user.entity.ts]")]
  node_roles_data[("Roles and permissions<br/>[role.entity.ts]")]
  node_email["Email verification<br/>[email.service.ts]"]
end

subgraph group_placement["Placement management"]
  node_profiles["Student profiles"]
  node_applications["Applications"]
  node_assignments["Placement assignments"]
  node_stages["Placement stages"]
  node_milestones["Milestones and deliverables"]
  node_subjects["Subject catalog"]
end

subgraph group_collaboration["Collaboration and AI"]
  node_chat["Chat and rooms<br/>[chat.service.ts]"]
  node_rag["Procedure knowledge API<br/>[rag.controller.ts]"]
  node_rag_logic["RAG service<br/>[rag.service.ts]"]
  node_analytics["Analytics"]
end

subgraph group_operations["Platform operations"]
  node_audit["Audit logging<br/>[audit.service.ts]"]
  node_audit_api["Audit API"]
  node_audit_interceptor["Audit interceptor"]
  node_application["Nest application<br/>[app.module.ts]"]
end

node_user(("API user"))

node_user -.->|"authenticates through"| node_auth_api
node_auth_api -->|"delegates to"| node_auth_logic
node_auth_logic -->|"reads and saves"| node_user_data
node_auth_logic -->|"loads role"| node_roles_data
node_auth_logic -->|"sends verification"| node_email
node_rag -->|"delegates to"| node_rag_logic
node_audit_api -->|"queries logs"| node_audit
node_audit_interceptor -->|"records events"| node_audit
node_application -->|"registers module"| node_auth_api
node_application -->|"registers module"| node_profiles
node_application -->|"registers module"| node_applications
node_application -->|"registers module"| node_assignments
node_application -->|"registers module"| node_stages
node_application -->|"registers module"| node_milestones
node_application -->|"registers module"| node_subjects
node_application -->|"registers module"| node_rag
node_application -->|"registers module"| node_analytics

click node_auth_api "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/auth/auth.controller.ts"
click node_auth_logic "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/auth/auth.service.ts"
click node_user_data "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/users/entities/user.entity.ts"
click node_roles_data "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/roles/entities/role.entity.ts"
click node_email "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/email/email.service.ts"
click node_profiles "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/profiles/profiles.controller.ts"
click node_applications "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/candidatures/candidatures.controller.ts"
click node_assignments "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/assignments/assignments.controller.ts"
click node_stages "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/stages/stages.controller.ts"
click node_milestones "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/jalons/jalons.controller.ts"
click node_subjects "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/subjects/subjects.controller.ts"
click node_chat "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/chat/chat.service.ts"
click node_rag "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/rag/rag.controller.ts"
click node_rag_logic "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/rag/rag.service.ts"
click node_analytics "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/analytics/analytics.controller.ts"
click node_audit "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/common/audit/audit.service.ts"
click node_audit_api "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/common/audit/audit.controller.ts"
click node_audit_interceptor "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/common/interceptors/audit.interceptor.ts"
click node_application "https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/app.module.ts"

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_auth_api,node_auth_logic,node_user_data,node_roles_data,node_email,node_user toneBlue
class node_profiles,node_applications,node_assignments,node_stages,node_milestones,node_subjects toneAmber
class node_chat,node_rag,node_rag_logic,node_analytics toneMint
class node_audit,node_audit_api,node_audit_interceptor,node_application toneRose
```

## Components

### Access and identity

- [Authentication API](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/auth/auth.controller.ts): `src/modules/auth/auth.controller.ts`
- [Authentication service](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/auth/auth.service.ts): `src/modules/auth/auth.service.ts`
- [User records](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/users/entities/user.entity.ts): `src/modules/users/entities/user.entity.ts`
- [Roles and permissions](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/roles/entities/role.entity.ts): `src/modules/roles/entities/role.entity.ts`
- [Email verification](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/email/email.service.ts): `src/modules/email/email.service.ts`

### Placement management

- [Student profiles](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/profiles/profiles.controller.ts): `src/modules/profiles/profiles.controller.ts`
- [Applications](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/candidatures/candidatures.controller.ts): `src/modules/candidatures/candidatures.controller.ts`
- [Placement assignments](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/assignments/assignments.controller.ts): `src/modules/assignments/assignments.controller.ts`
- [Placement stages](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/stages/stages.controller.ts): `src/modules/stages/stages.controller.ts`
- [Milestones and deliverables](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/jalons/jalons.controller.ts): `src/modules/jalons/jalons.controller.ts`
- [Subject catalog](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/subjects/subjects.controller.ts): `src/modules/subjects/subjects.controller.ts`

### Collaboration and AI

- [Chat and rooms](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/chat/chat.service.ts): `src/modules/chat/chat.service.ts`
- [Procedure knowledge API](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/rag/rag.controller.ts): `src/modules/rag/rag.controller.ts`
- [RAG service](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/rag/rag.service.ts): `src/modules/rag/rag.service.ts`
- [Analytics](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/modules/analytics/analytics.controller.ts): `src/modules/analytics/analytics.controller.ts`

### Platform operations

- [Audit logging](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/common/audit/audit.service.ts): `src/common/audit/audit.service.ts`
- [Audit API](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/common/audit/audit.controller.ts): `src/common/audit/audit.controller.ts`
- [Audit interceptor](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/common/interceptors/audit.interceptor.ts): `src/common/interceptors/audit.interceptor.ts`
- [Nest application](https://github.com/jihedsaguer/neurostage_ai_backend/blob/master/src/app.module.ts): `src/app.module.ts`

### Other components

- **API user**

## Connections

- API user → Authentication API: authenticates through
- Authentication API → Authentication service: delegates to (evidence: `src/modules/auth/auth.service.ts`)
- Authentication service → User records: reads and saves (evidence: `src/modules/auth/auth.service.ts`)
- Authentication service → Roles and permissions: loads role (evidence: `src/modules/auth/auth.service.ts`)
- Authentication service → Email verification: sends verification (evidence: `src/modules/auth/auth.service.ts`)
- Procedure knowledge API → RAG service: delegates to (evidence: `src/modules/rag/rag.controller.ts`)
- Audit API → Audit logging: queries logs (evidence: `src/common/audit/audit.controller.ts`)
- Audit interceptor → Audit logging: records events (evidence: `src/common/interceptors/audit.interceptor.ts`)
- Nest application → Authentication API: registers module (evidence: `src/app.module.ts`)
- Nest application → Student profiles: registers module (evidence: `src/app.module.ts`)
- Nest application → Applications: registers module (evidence: `src/app.module.ts`)
- Nest application → Placement assignments: registers module (evidence: `src/app.module.ts`)
- Nest application → Placement stages: registers module (evidence: `src/app.module.ts`)
- Nest application → Milestones and deliverables: registers module (evidence: `src/app.module.ts`)
- Nest application → Subject catalog: registers module (evidence: `src/app.module.ts`)
- Nest application → Procedure knowledge API: registers module (evidence: `src/app.module.ts`)
- Nest application → Analytics: registers module (evidence: `src/app.module.ts`)