# devacharya80/pointerai architecture

> Architecture diagram of the GitHub repository devacharya80/pointerai, 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/devacharya80/pointerai
- Repository: https://github.com/devacharya80/pointerai

## Overview

PointerAI is an adaptive AI learning workspace. A student signs in, opens or creates a conversation, and sends a question; the server may ask for clarification, then streams an answer informed by profile and remembered facts, with optional web sources, and saves the result. The graph preserves the documented auth, profile, conversation, personalization, search, and rate-limiting capabilities. Several backend subsystems are represented at directory level because their individual files were not sampled; links there rely on README documentation or indexed references.

Main entry points: [`server/src/modules/conversations/message.service.ts`](https://github.com/devacharya80/pointerai/blob/main/server/src/modules/conversations/message.service.ts) (Message orchestration), [`server/src/app.ts`](https://github.com/devacharya80/pointerai/blob/main/server/src/app.ts) (Express API), [`client/src/App.tsx`](https://github.com/devacharya80/pointerai/blob/main/client/src/App.tsx) (Web app), [`client/src/hooks/useChat.ts`](https://github.com/devacharya80/pointerai/blob/main/client/src/hooks/useChat.ts) (Chat interaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Student workspace"]
  node_app["Web app<br/>[App.tsx]"]
  node_auth_ui["Auth session UI<br/>[AuthContext.tsx]"]
  node_auth_api["Auth API client<br/>[auth.ts]"]
  node_chat_ui["Chat workspace<br/>[Chat.tsx]"]
  node_chat_hook["Chat interaction<br/>[useChat.ts]"]
  node_conversation_api["Conversation API<br/>[conversations.ts]"]
  node_stream_api["Stream client<br/>[stream.ts]"]
end

subgraph group_identity["Identity and access"]
  node_auth_routes["Auth routes<br/>[auth.route.ts]"]
  node_auth_controller["Auth controller<br/>[auth.controller.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_oauth["Google OAuth<br/>[passport.config.ts]"]
end

subgraph group_learning["Conversation learning"]
  node_profile["Learning profile"]
  node_conversation_routes["Conversation routes"]
  node_conversation_controller["Conversation controller"]
  node_message_controller["Message controller"]
  node_message_service["Message orchestration<br/>[message.service.ts]"]
  node_adaptive["Adaptive questioning"]
  node_personalization["Profile and memory"]
  node_search["Web search<br/>[tavily.provider.ts]"]
  node_ai_service["AI abstraction<br/>[ai.service.ts]"]
  node_groq["Groq provider<br/>[groq.provider.ts]"]
end

subgraph group_platform["API and state"]
  node_api_app["Express API<br/>[app.ts]"]
  node_rate_limit["Rate limiting"]
  node_postgres[("PostgreSQL<br/>[prisma.ts]")]
  node_redis[("Redis<br/>[redis.ts]")]
end

node_student(("Student"))
node_tavily{{"Tavily service"}}

node_student -->|"uses"| node_app
node_app -->|"provides session"| node_auth_ui
node_app -->|"routes to"| node_chat_ui
node_student -->|"signs in"| node_auth_api
node_auth_ui -->|"restores session"| node_auth_api
node_chat_ui -->|"uses"| node_chat_hook
node_chat_hook -->|"loads conversations"| node_conversation_api
node_chat_hook -->|"streams messages"| node_stream_api
node_auth_api -->|"calls auth endpoints"| node_api_app
node_conversation_api -->|"calls conversation endpoints"| node_api_app
node_api_app -->|"mounts"| node_auth_routes
node_api_app -->|"mounts"| node_conversation_routes
node_api_app -->|"mounts"| node_profile
node_api_app -->|"applies"| node_rate_limit
node_auth_routes -->|"routes requests"| node_auth_controller
node_auth_controller -->|"delegates auth"| node_auth_service
node_auth_controller -.->|"uses OAuth strategy"| node_oauth
node_auth_service -->|"reads and writes"| node_postgres
node_conversation_routes -->|"routes conversations"| node_conversation_controller
node_conversation_routes -->|"routes messages"| node_message_controller
node_conversation_controller -->|"manages conversations"| node_message_service
node_message_controller -->|"prepares and saves"| node_message_service
node_message_controller -->|"requests stream"| node_ai_service
node_message_service -->|"classifies ambiguity"| node_adaptive
node_message_service -->|"builds context"| node_personalization
node_message_service -->|"searches when needed"| node_search
node_message_service -->|"prepares AI context"| node_ai_service
node_message_service -->|"persists messages"| node_postgres
node_profile -.->|"stores profile"| node_postgres
node_ai_service -->|"dispatches generation"| node_groq
node_search -.->|"fetches sources"| node_tavily
node_rate_limit -.->|"checks limits"| node_redis

click node_app "https://github.com/devacharya80/pointerai/blob/main/client/src/App.tsx"
click node_auth_ui "https://github.com/devacharya80/pointerai/blob/main/client/src/context/AuthContext.tsx"
click node_auth_api "https://github.com/devacharya80/pointerai/blob/main/client/src/api/auth.ts"
click node_chat_ui "https://github.com/devacharya80/pointerai/blob/main/client/src/pages/Chat.tsx"
click node_chat_hook "https://github.com/devacharya80/pointerai/blob/main/client/src/hooks/useChat.ts"
click node_conversation_api "https://github.com/devacharya80/pointerai/blob/main/client/src/api/conversations.ts"
click node_stream_api "https://github.com/devacharya80/pointerai/blob/main/client/src/api/stream.ts"
click node_auth_routes "https://github.com/devacharya80/pointerai/blob/main/server/src/modules/auth/auth.route.ts"
click node_auth_controller "https://github.com/devacharya80/pointerai/blob/main/server/src/modules/auth/auth.controller.ts"
click node_auth_service "https://github.com/devacharya80/pointerai/blob/main/server/src/modules/auth/auth.service.ts"
click node_oauth "https://github.com/devacharya80/pointerai/blob/main/server/src/modules/auth/passport.config.ts"
click node_profile "https://github.com/devacharya80/pointerai/tree/main/server/src/modules/profile"
click node_conversation_routes "https://github.com/devacharya80/pointerai/blob/main/server/src/modules/conversations/conversation.routes.ts"
click node_conversation_controller "https://github.com/devacharya80/pointerai/blob/main/server/src/modules/conversations/conversation.controller.ts"
click node_message_controller "https://github.com/devacharya80/pointerai/blob/main/server/src/modules/conversations/message.controller.ts"
click node_message_service "https://github.com/devacharya80/pointerai/blob/main/server/src/modules/conversations/message.service.ts"
click node_adaptive "https://github.com/devacharya80/pointerai/tree/main/server/src/modules/conversations/utils"
click node_personalization "https://github.com/devacharya80/pointerai/tree/main/server/src/modules/conversations/utils"
click node_search "https://github.com/devacharya80/pointerai/blob/main/server/src/modules/conversations/providers/tavily.provider.ts"
click node_ai_service "https://github.com/devacharya80/pointerai/blob/main/server/src/modules/ai/ai.service.ts"
click node_groq "https://github.com/devacharya80/pointerai/blob/main/server/src/modules/ai/providers/groq.provider.ts"
click node_api_app "https://github.com/devacharya80/pointerai/blob/main/server/src/app.ts"
click node_rate_limit "https://github.com/devacharya80/pointerai/blob/main/server/src/middleware/rateLimit.middleware.ts"
click node_postgres "https://github.com/devacharya80/pointerai/blob/main/server/src/lib/prisma.ts"
click node_redis "https://github.com/devacharya80/pointerai/blob/main/server/src/lib/redis.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_auth_ui,node_auth_api,node_chat_ui,node_chat_hook,node_conversation_api,node_stream_api toneBlue
class node_auth_routes,node_auth_controller,node_auth_service,node_oauth toneAmber
class node_profile,node_conversation_routes,node_conversation_controller,node_message_controller,node_message_service,node_adaptive,node_personalization,node_search,node_ai_service,node_groq toneMint
class node_api_app,node_rate_limit,node_postgres,node_redis toneRose
class node_student,node_tavily toneIndigo
```

## Components

### Student workspace

- [Web app](https://github.com/devacharya80/pointerai/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Auth session UI](https://github.com/devacharya80/pointerai/blob/main/client/src/context/AuthContext.tsx): `client/src/context/AuthContext.tsx`
- [Auth API client](https://github.com/devacharya80/pointerai/blob/main/client/src/api/auth.ts): `client/src/api/auth.ts`
- [Chat workspace](https://github.com/devacharya80/pointerai/blob/main/client/src/pages/Chat.tsx): `client/src/pages/Chat.tsx`
- [Chat interaction](https://github.com/devacharya80/pointerai/blob/main/client/src/hooks/useChat.ts): `client/src/hooks/useChat.ts`
- [Conversation API](https://github.com/devacharya80/pointerai/blob/main/client/src/api/conversations.ts): `client/src/api/conversations.ts`
- [Stream client](https://github.com/devacharya80/pointerai/blob/main/client/src/api/stream.ts): `client/src/api/stream.ts`

### Identity and access

- [Auth routes](https://github.com/devacharya80/pointerai/blob/main/server/src/modules/auth/auth.route.ts): `server/src/modules/auth/auth.route.ts`
- [Auth controller](https://github.com/devacharya80/pointerai/blob/main/server/src/modules/auth/auth.controller.ts): `server/src/modules/auth/auth.controller.ts`
- [Auth service](https://github.com/devacharya80/pointerai/blob/main/server/src/modules/auth/auth.service.ts): `server/src/modules/auth/auth.service.ts`
- [Google OAuth](https://github.com/devacharya80/pointerai/blob/main/server/src/modules/auth/passport.config.ts): `server/src/modules/auth/passport.config.ts`

### Conversation learning

- [Learning profile](https://github.com/devacharya80/pointerai/tree/main/server/src/modules/profile): `server/src/modules/profile`
- [Conversation routes](https://github.com/devacharya80/pointerai/blob/main/server/src/modules/conversations/conversation.routes.ts): `server/src/modules/conversations/conversation.routes.ts`
- [Conversation controller](https://github.com/devacharya80/pointerai/blob/main/server/src/modules/conversations/conversation.controller.ts): `server/src/modules/conversations/conversation.controller.ts`
- [Message controller](https://github.com/devacharya80/pointerai/blob/main/server/src/modules/conversations/message.controller.ts): `server/src/modules/conversations/message.controller.ts`
- [Message orchestration](https://github.com/devacharya80/pointerai/blob/main/server/src/modules/conversations/message.service.ts): `server/src/modules/conversations/message.service.ts`
- [Adaptive questioning](https://github.com/devacharya80/pointerai/tree/main/server/src/modules/conversations/utils): `server/src/modules/conversations/utils`
- [Profile and memory](https://github.com/devacharya80/pointerai/tree/main/server/src/modules/conversations/utils): `server/src/modules/conversations/utils`
- [Web search](https://github.com/devacharya80/pointerai/blob/main/server/src/modules/conversations/providers/tavily.provider.ts): `server/src/modules/conversations/providers/tavily.provider.ts`
- [AI abstraction](https://github.com/devacharya80/pointerai/blob/main/server/src/modules/ai/ai.service.ts): `server/src/modules/ai/ai.service.ts`
- [Groq provider](https://github.com/devacharya80/pointerai/blob/main/server/src/modules/ai/providers/groq.provider.ts): `server/src/modules/ai/providers/groq.provider.ts`

### API and state

- [Express API](https://github.com/devacharya80/pointerai/blob/main/server/src/app.ts): `server/src/app.ts`
- [Rate limiting](https://github.com/devacharya80/pointerai/blob/main/server/src/middleware/rateLimit.middleware.ts): `server/src/middleware/rateLimit.middleware.ts`
- [PostgreSQL](https://github.com/devacharya80/pointerai/blob/main/server/src/lib/prisma.ts): `server/src/lib/prisma.ts`
- [Redis](https://github.com/devacharya80/pointerai/blob/main/server/src/lib/redis.ts): `server/src/lib/redis.ts`

### Other components

- **Student**
- **Tavily service**

## Connections

- Student → Web app: uses (evidence: `client/src/App.tsx`)
- Web app → Auth session UI: provides session (evidence: `client/src/main.tsx`)
- Web app → Chat workspace: routes to (evidence: `client/src/App.tsx`)
- Student → Auth API client: signs in (evidence: `client/src/api/auth.ts`)
- Auth session UI → Auth API client: restores session (evidence: `client/src/context/AuthContext.tsx`)
- Chat workspace → Chat interaction: uses (evidence: `client/src/hooks/useChat.ts`)
- Chat interaction → Conversation API: loads conversations (evidence: `client/src/hooks/useChat.ts`)
- Chat interaction → Stream client: streams messages (evidence: `client/src/hooks/useChat.ts`)
- Auth API client → Express API: calls auth endpoints (evidence: `client/src/api/auth.ts`)
- Conversation API → Express API: calls conversation endpoints (evidence: `client/src/api/conversations.ts`)
- Express API → Auth routes: mounts (evidence: `server/src/app.ts`)
- Express API → Conversation routes: mounts (evidence: `server/src/app.ts`)
- Express API → Learning profile: mounts (evidence: `server/src/app.ts`)
- Express API → Rate limiting: applies (evidence: `server/src/app.ts`)
- Auth routes → Auth controller: routes requests (evidence: `server/src/modules/auth/auth.controller.ts`)
- Auth controller → Auth service: delegates auth (evidence: `server/src/modules/auth/auth.controller.ts`)
- Auth controller → Google OAuth: uses OAuth strategy (evidence: `README.md`)
- Auth service → PostgreSQL: reads and writes (evidence: `server/src/modules/auth/auth.service.ts`)
- Conversation routes → Conversation controller: routes conversations (evidence: `server/src/modules/conversations/conversation.routes.ts`)
- Conversation routes → Message controller: routes messages (evidence: `server/src/modules/conversations/conversation.routes.ts`)
- Conversation controller → Message orchestration: manages conversations (evidence: `server/src/modules/conversations/conversation.controller.ts`)
- Message controller → Message orchestration: prepares and saves (evidence: `server/src/modules/conversations/message.controller.ts`)
- Message controller → AI abstraction: requests stream (evidence: `server/src/modules/conversations/message.controller.ts`)
- Message orchestration → Adaptive questioning: classifies ambiguity (evidence: `server/src/modules/conversations/message.service.ts`)
- Message orchestration → Profile and memory: builds context (evidence: `server/src/modules/conversations/message.service.ts`)
- Message orchestration → Web search: searches when needed (evidence: `server/src/modules/conversations/message.service.ts`)
- Message orchestration → AI abstraction: prepares AI context (evidence: `server/src/modules/conversations/message.service.ts`)
- Message orchestration → PostgreSQL: persists messages (evidence: `server/src/modules/conversations/message.service.ts`)
- Learning profile → PostgreSQL: stores profile (evidence: `README.md`)
- AI abstraction → Groq provider: dispatches generation (evidence: `server/src/modules/ai/ai.service.ts`)
- Web search → Tavily service: fetches sources (evidence: `README.md`)
- Rate limiting → Redis: checks limits (evidence: `README.md`)