# norabino/ft_transcendence architecture

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

- Interactive diagram: https://gitdiagram.com/norabino/ft_transcendence
- Repository: https://github.com/norabino/ft_transcendence

## Overview

ft_transcendence is a social-network web app: users authenticate, browse a feed and public profiles, manage friendships, and use real-time chat and AI features. The frontend routes pages and composes UI with shared stores and API/socket clients; NestJS controllers delegate domain operations to services backed by Prisma. The README documents OAuth, 2FA, presence, and hybrid AI capabilities. Some backend gateways and several frontend modules were not excerpted, so uncertain runtime links are omitted or marked unverified.

Main entry points: [`backend/src/prisma/prisma.service.ts`](https://github.com/norabino/ft_transcendence/blob/main/backend/src/prisma/prisma.service.ts) (Prisma data access), [`frontend/src/App.tsx`](https://github.com/norabino/ft_transcendence/blob/main/frontend/src/App.tsx) (App routing), [`frontend/src/pages/PublicProfile.tsx`](https://github.com/norabino/ft_transcendence/blob/main/frontend/src/pages/PublicProfile.tsx) (Public profile), [`backend/src/auth/auth.controller.ts`](https://github.com/norabino/ft_transcendence/blob/main/backend/src/auth/auth.controller.ts) (Auth endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web experience"]
  node_app["App routing<br/>[App.tsx]"]
  node_feed["Home feed<br/>[HomeFeed.tsx]"]
  node_profile_page["Public profile<br/>[PublicProfile.tsx]"]
  node_auth_ui["Auth modals<br/>[AuthModals.tsx]"]
  node_auth_state["Auth state<br/>[authStore.ts]"]
  node_http_client["HTTP client<br/>[axios.ts]"]
  node_social_ui["Social sidebar<br/>[SocialSidebar.tsx]"]
  node_social_state["Social state<br/>[socialStore.ts]"]
  node_chat_ui["Global chat UI"]
  node_socket_hook["Socket hook<br/>[useSocket.ts]"]
  node_ai_api["AI API client<br/>[aiApi.ts]"]
end

subgraph group_identity["Identity and access"]
  node_auth_controller["Auth endpoints<br/>[auth.controller.ts]"]
  node_auth_service["Authentication<br/>[auth.service.ts]"]
  node_two_factor["2FA service"]
  node_oauth["42 OAuth strategy"]
end

subgraph group_social["Social features"]
  node_users["User profiles<br/>[users.service.ts]"]
  node_friends_controller["Friend endpoints"]
  node_friends_service["Friend management<br/>[friends.service.ts]"]
  node_posts_controller["Post endpoints"]
  node_posts_service["Posts<br/>[posts.service.ts]"]
end

subgraph group_realtime_ai["Realtime and AI"]
  node_chat_controller["Chat endpoints<br/>[chat.controller.ts]"]
  node_chat_service["Messaging<br/>[chat.service.ts]"]
  node_chat_gateway["Chat gateway<br/>[chat.gateway.ts]"]
  node_friends_gateway["Presence gateway<br/>[friends.gateway.ts]"]
  node_ai_controller["AI endpoints<br/>[ai.controller.ts]"]
  node_ai_service["AI orchestration<br/>[ai.service.ts]"]
end

subgraph group_backend_data["Backend and data"]
  node_prisma[("Prisma data access<br/>[prisma.service.ts]")]
  node_backend_app["Nest app composition<br/>[app.module.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_feed
node_app -->|"routes to"| node_profile_page
node_app -->|"renders"| node_chat_ui
node_feed -->|"opens"| node_auth_ui
node_profile_page -->|"renders"| node_auth_ui
node_auth_ui -->|"submits requests"| node_http_client
node_auth_ui -->|"updates"| node_auth_state
node_http_client -->|"updates session"| node_auth_state
node_profile_page -->|"fetches profile"| node_http_client
node_profile_page -->|"renders"| node_social_ui
node_social_ui -->|"uses"| node_social_state
node_social_state -->|"requests social data"| node_http_client
node_chat_ui -->|"requests AI"| node_ai_api
node_chat_ui -->|"uses socket"| node_socket_hook
node_socket_hook -->|"updates presence"| node_social_state
node_auth_controller -->|"delegates to"| node_auth_service
node_auth_controller -->|"uses"| node_two_factor
node_auth_controller -->|"uses"| node_users
node_friends_controller -->|"delegates to"| node_friends_service
node_posts_controller -->|"delegates to"| node_posts_service
node_chat_controller -->|"delegates to"| node_chat_service
node_ai_controller -->|"delegates to"| node_ai_service
node_auth_service -->|"queries"| node_prisma
node_two_factor -->|"reads and writes"| node_prisma
node_friends_service -->|"queries"| node_prisma
node_posts_service -->|"queries"| node_prisma
node_users -->|"queries"| node_prisma
node_chat_service -->|"queries"| node_prisma
node_ai_service -->|"uses"| node_prisma
node_backend_app -->|"registers module"| node_auth_controller
node_backend_app -->|"configures provider"| node_prisma
node_oauth -.->|"validates identity"| node_auth_service
node_chat_gateway -.->|"dispatches messages"| node_chat_service
node_friends_gateway -.->|"dispatches presence"| node_friends_service
node_ai_api -.->|"calls backend"| node_ai_controller

click node_app "https://github.com/norabino/ft_transcendence/blob/main/frontend/src/App.tsx"
click node_feed "https://github.com/norabino/ft_transcendence/blob/main/frontend/src/pages/HomeFeed.tsx"
click node_profile_page "https://github.com/norabino/ft_transcendence/blob/main/frontend/src/pages/PublicProfile.tsx"
click node_auth_ui "https://github.com/norabino/ft_transcendence/blob/main/frontend/src/components/AuthModals.tsx"
click node_auth_state "https://github.com/norabino/ft_transcendence/blob/main/frontend/src/store/authStore.ts"
click node_http_client "https://github.com/norabino/ft_transcendence/blob/main/frontend/src/api/axios.ts"
click node_social_ui "https://github.com/norabino/ft_transcendence/blob/main/frontend/src/components/SocialSidebar.tsx"
click node_social_state "https://github.com/norabino/ft_transcendence/blob/main/frontend/src/store/socialStore.ts"
click node_chat_ui "https://github.com/norabino/ft_transcendence/blob/main/frontend/src/components/GlobalChatWidget.tsx"
click node_socket_hook "https://github.com/norabino/ft_transcendence/blob/main/frontend/src/hooks/useSocket.ts"
click node_ai_api "https://github.com/norabino/ft_transcendence/blob/main/frontend/src/api/aiApi.ts"
click node_auth_controller "https://github.com/norabino/ft_transcendence/blob/main/backend/src/auth/auth.controller.ts"
click node_auth_service "https://github.com/norabino/ft_transcendence/blob/main/backend/src/auth/auth.service.ts"
click node_two_factor "https://github.com/norabino/ft_transcendence/blob/main/backend/src/auth/2fa/two-factor-auth.service.ts"
click node_oauth "https://github.com/norabino/ft_transcendence/blob/main/backend/src/auth/42auth/forty-two.strategy.ts"
click node_users "https://github.com/norabino/ft_transcendence/blob/main/backend/src/users/users.service.ts"
click node_friends_controller "https://github.com/norabino/ft_transcendence/blob/main/backend/src/friends/friends.controller.ts"
click node_friends_service "https://github.com/norabino/ft_transcendence/blob/main/backend/src/friends/friends.service.ts"
click node_posts_controller "https://github.com/norabino/ft_transcendence/blob/main/backend/src/posts/posts.controller.ts"
click node_posts_service "https://github.com/norabino/ft_transcendence/blob/main/backend/src/posts/posts.service.ts"
click node_chat_controller "https://github.com/norabino/ft_transcendence/blob/main/backend/src/chat/chat.controller.ts"
click node_chat_service "https://github.com/norabino/ft_transcendence/blob/main/backend/src/chat/chat.service.ts"
click node_chat_gateway "https://github.com/norabino/ft_transcendence/blob/main/backend/src/chat/chat.gateway.ts"
click node_friends_gateway "https://github.com/norabino/ft_transcendence/blob/main/backend/src/friends/friends.gateway.ts"
click node_ai_controller "https://github.com/norabino/ft_transcendence/blob/main/backend/src/ai/ai.controller.ts"
click node_ai_service "https://github.com/norabino/ft_transcendence/blob/main/backend/src/ai/ai.service.ts"
click node_prisma "https://github.com/norabino/ft_transcendence/blob/main/backend/src/prisma/prisma.service.ts"
click node_backend_app "https://github.com/norabino/ft_transcendence/blob/main/backend/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_app,node_feed,node_profile_page,node_auth_ui,node_auth_state,node_http_client,node_social_ui,node_social_state,node_chat_ui,node_socket_hook,node_ai_api,node_user toneBlue
class node_auth_controller,node_auth_service,node_two_factor,node_oauth toneAmber
class node_users,node_friends_controller,node_friends_service,node_posts_controller,node_posts_service toneMint
class node_chat_controller,node_chat_service,node_chat_gateway,node_friends_gateway,node_ai_controller,node_ai_service toneRose
class node_prisma,node_backend_app toneIndigo
```

## Components

### Web experience

- [App routing](https://github.com/norabino/ft_transcendence/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Home feed](https://github.com/norabino/ft_transcendence/blob/main/frontend/src/pages/HomeFeed.tsx): `frontend/src/pages/HomeFeed.tsx`
- [Public profile](https://github.com/norabino/ft_transcendence/blob/main/frontend/src/pages/PublicProfile.tsx): `frontend/src/pages/PublicProfile.tsx`
- [Auth modals](https://github.com/norabino/ft_transcendence/blob/main/frontend/src/components/AuthModals.tsx): `frontend/src/components/AuthModals.tsx`
- [Auth state](https://github.com/norabino/ft_transcendence/blob/main/frontend/src/store/authStore.ts): `frontend/src/store/authStore.ts`
- [HTTP client](https://github.com/norabino/ft_transcendence/blob/main/frontend/src/api/axios.ts): `frontend/src/api/axios.ts`
- [Social sidebar](https://github.com/norabino/ft_transcendence/blob/main/frontend/src/components/SocialSidebar.tsx): `frontend/src/components/SocialSidebar.tsx`
- [Social state](https://github.com/norabino/ft_transcendence/blob/main/frontend/src/store/socialStore.ts): `frontend/src/store/socialStore.ts`
- [Global chat UI](https://github.com/norabino/ft_transcendence/blob/main/frontend/src/components/GlobalChatWidget.tsx): `frontend/src/components/GlobalChatWidget.tsx`
- [Socket hook](https://github.com/norabino/ft_transcendence/blob/main/frontend/src/hooks/useSocket.ts): `frontend/src/hooks/useSocket.ts`
- [AI API client](https://github.com/norabino/ft_transcendence/blob/main/frontend/src/api/aiApi.ts): `frontend/src/api/aiApi.ts`

### Identity and access

- [Auth endpoints](https://github.com/norabino/ft_transcendence/blob/main/backend/src/auth/auth.controller.ts): `backend/src/auth/auth.controller.ts`
- [Authentication](https://github.com/norabino/ft_transcendence/blob/main/backend/src/auth/auth.service.ts): `backend/src/auth/auth.service.ts`
- [2FA service](https://github.com/norabino/ft_transcendence/blob/main/backend/src/auth/2fa/two-factor-auth.service.ts): `backend/src/auth/2fa/two-factor-auth.service.ts`
- [42 OAuth strategy](https://github.com/norabino/ft_transcendence/blob/main/backend/src/auth/42auth/forty-two.strategy.ts): `backend/src/auth/42auth/forty-two.strategy.ts`

### Social features

- [User profiles](https://github.com/norabino/ft_transcendence/blob/main/backend/src/users/users.service.ts): `backend/src/users/users.service.ts`
- [Friend endpoints](https://github.com/norabino/ft_transcendence/blob/main/backend/src/friends/friends.controller.ts): `backend/src/friends/friends.controller.ts`
- [Friend management](https://github.com/norabino/ft_transcendence/blob/main/backend/src/friends/friends.service.ts): `backend/src/friends/friends.service.ts`
- [Post endpoints](https://github.com/norabino/ft_transcendence/blob/main/backend/src/posts/posts.controller.ts): `backend/src/posts/posts.controller.ts`
- [Posts](https://github.com/norabino/ft_transcendence/blob/main/backend/src/posts/posts.service.ts): `backend/src/posts/posts.service.ts`

### Realtime and AI

- [Chat endpoints](https://github.com/norabino/ft_transcendence/blob/main/backend/src/chat/chat.controller.ts): `backend/src/chat/chat.controller.ts`
- [Messaging](https://github.com/norabino/ft_transcendence/blob/main/backend/src/chat/chat.service.ts): `backend/src/chat/chat.service.ts`
- [Chat gateway](https://github.com/norabino/ft_transcendence/blob/main/backend/src/chat/chat.gateway.ts): `backend/src/chat/chat.gateway.ts`
- [Presence gateway](https://github.com/norabino/ft_transcendence/blob/main/backend/src/friends/friends.gateway.ts): `backend/src/friends/friends.gateway.ts`
- [AI endpoints](https://github.com/norabino/ft_transcendence/blob/main/backend/src/ai/ai.controller.ts): `backend/src/ai/ai.controller.ts`
- [AI orchestration](https://github.com/norabino/ft_transcendence/blob/main/backend/src/ai/ai.service.ts): `backend/src/ai/ai.service.ts`

### Backend and data

- [Prisma data access](https://github.com/norabino/ft_transcendence/blob/main/backend/src/prisma/prisma.service.ts): `backend/src/prisma/prisma.service.ts`
- [Nest app composition](https://github.com/norabino/ft_transcendence/blob/main/backend/src/app.module.ts): `backend/src/app.module.ts`

### Other components

- **User**

## Connections

- User → App routing: uses (evidence: `frontend/src/App.tsx`)
- App routing → Home feed: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Public profile: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Global chat UI: renders (evidence: `frontend/src/App.tsx`)
- Home feed → Auth modals: opens (evidence: `frontend/src/pages/HomeFeed.tsx`)
- Public profile → Auth modals: renders (evidence: `frontend/src/pages/PublicProfile.tsx`)
- Auth modals → HTTP client: submits requests (evidence: `frontend/src/components/AuthModals.tsx`)
- Auth modals → Auth state: updates (evidence: `frontend/src/components/AuthModals.tsx`)
- HTTP client → Auth state: updates session (evidence: `frontend/src/api/axios.ts`)
- Public profile → HTTP client: fetches profile (evidence: `frontend/src/pages/PublicProfile.tsx`)
- Public profile → Social sidebar: renders (evidence: `frontend/src/pages/PublicProfile.tsx`)
- Social sidebar → Social state: uses (evidence: `frontend/src/components/SocialSidebar.tsx`)
- Social state → HTTP client: requests social data (evidence: `frontend/src/store/socialStore.ts`)
- Global chat UI → AI API client: requests AI (evidence: `frontend/src/components/GlobalChatWidget.tsx`)
- Global chat UI → Socket hook: uses socket (evidence: `frontend/src/components/GlobalChatWidget.tsx`)
- Socket hook → Social state: updates presence (evidence: `frontend/src/hooks/useSocket.ts`)
- Auth endpoints → Authentication: delegates to (evidence: `backend/src/auth/auth.controller.ts`)
- Auth endpoints → 2FA service: uses (evidence: `backend/src/auth/auth.controller.ts`)
- Auth endpoints → User profiles: uses (evidence: `backend/src/auth/auth.controller.ts`)
- Friend endpoints → Friend management: delegates to (evidence: `backend/src/friends/friends.controller.ts`)
- Post endpoints → Posts: delegates to (evidence: `backend/src/posts/posts.controller.ts`)
- Chat endpoints → Messaging: delegates to (evidence: `backend/src/chat/chat.controller.ts`)
- AI endpoints → AI orchestration: delegates to (evidence: `backend/src/ai/ai.controller.ts`)
- Authentication → Prisma data access: queries (evidence: `backend/src/auth/auth.service.ts`)
- 2FA service → Prisma data access: reads and writes (evidence: `backend/src/auth/2fa/two-factor-auth.service.ts`)
- Friend management → Prisma data access: queries (evidence: `backend/src/friends/friends.service.ts`)
- Posts → Prisma data access: queries (evidence: `backend/src/posts/posts.service.ts`)
- User profiles → Prisma data access: queries (evidence: `backend/src/users/users.service.ts`)
- Messaging → Prisma data access: queries (evidence: `backend/src/chat/chat.service.ts`)
- AI orchestration → Prisma data access: uses (evidence: `backend/src/ai/ai.service.ts`)
- Nest app composition → Auth endpoints: registers module (evidence: `backend/src/app.module.ts`)
- Nest app composition → Prisma data access: configures provider (evidence: `backend/src/app.module.ts`)
- 42 OAuth strategy → Authentication: validates identity
- Chat gateway → Messaging: dispatches messages
- Presence gateway → Friend management: dispatches presence (evidence: `backend/src/friends/friends.service.ts`)
- AI API client → AI endpoints: calls backend
