# tktarun03/beyond-obvious-ai-student-lab architecture

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

- Interactive diagram: https://gitdiagram.com/tktarun03/beyond-obvious-ai-student-lab
- Repository: https://github.com/tktarun03/beyond-obvious-ai-student-lab

## Overview

This is a learning lab with a working catalogue portal and shared production-minded AI engineering packages; the five project workspaces are documented product concepts but are still scaffolded. The visible user workflow is choosing a project from the portal, which links to its workspace; the documented project goals describe the intended domain stages. Shared packages provide validation, authentication, AI, persistence, observability, and evaluation. Project internals and several package wiring details were not sampled, so those connections are omitted or identified as documented rather than inferred.

Main entry points: [`packages/ai/src/providers/gemini.ts`](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/ai/src/providers/gemini.ts) (Gemini provider), [`packages/auth/src/route.ts`](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/auth/src/route.ts) (Authenticated routes), [`apps/portal/src/components/ServerStatusPanel.tsx`](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/apps/portal/src/components/ServerStatusPanel.tsx) (Server status), [`projects/01-knowledge-copilot`](https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/projects/01-knowledge-copilot) (Knowledge copilot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Catalogue portal"]
  node_portalpage["Catalogue page<br/>[page.tsx]"]
  node_catalogue["Project catalogue<br/>[catalogue.ts]"]
  node_projectcard["Project cards<br/>[ProjectCard.tsx]"]
  node_statuspanel["Server status"]
end

subgraph group_projects["Learning projects"]
  node_copilot["Knowledge copilot"]
  node_documents["Document intelligence"]
  node_voice["Voice assistant"]
  node_engineering["Engineering agent"]
  node_decisions["Decision assistant"]
end

subgraph group_boundaries["Application boundaries"]
  node_validation["Input validation<br/>[upload.ts]"]
  node_authroute["Authenticated routes<br/>[route.ts]"]
  node_authfactory["Auth selection<br/>[factory.ts]"]
  node_devauth["Development auth<br/>[dev-provider.ts]"]
  node_firebaseauth["Firebase auth"]
  node_ratelimit["Rate limiting<br/>[rate-limit.ts]"]
  node_database[("Database adapters")]
end

subgraph group_ai["AI and evaluation"]
  node_gemini["Gemini provider<br/>[gemini.ts]"]
  node_embedding["Mock embeddings<br/>[embedding.ts]"]
  node_retry["Retry policy<br/>[retry.ts]"]
  node_toolselection["Tool selection<br/>[tool-selection.ts]"]
  node_evals["Evaluation framework"]
  node_scorers["Evaluation scorers<br/>[scorers.ts]"]
end

subgraph group_foundation["Shared foundation"]
  node_observability["Observability"]
  node_ui["Shared UI primitives"]
  node_shared["Shared utilities"]
end

node_learner(("Learner"))

node_learner -->|"opens"| node_portalpage
node_portalpage -->|"reads"| node_catalogue
node_portalpage -->|"renders"| node_projectcard
node_portalpage -->|"renders"| node_statuspanel
node_projectcard -->|"uses data"| node_catalogue
node_statuspanel -->|"checks status"| node_copilot
node_statuspanel -->|"checks status"| node_documents
node_statuspanel -->|"checks status"| node_voice
node_statuspanel -->|"checks status"| node_engineering
node_statuspanel -->|"checks status"| node_decisions
node_portalpage -->|"uses components"| node_ui
node_projectcard -->|"uses components"| node_ui
node_copilot -.->|"validates input"| node_validation
node_copilot -.->|"authenticates"| node_authroute
node_copilot -.->|"requests AI"| node_gemini
node_copilot -.->|"persists data"| node_database
node_documents -.->|"validates input"| node_validation
node_documents -.->|"authenticates"| node_authroute
node_documents -.->|"requests AI"| node_gemini
node_documents -.->|"persists data"| node_database
node_voice -.->|"validates input"| node_validation
node_voice -.->|"authenticates"| node_authroute
node_voice -.->|"requests AI"| node_gemini
node_voice -.->|"persists data"| node_database
node_engineering -.->|"validates input"| node_validation
node_engineering -.->|"authenticates"| node_authroute
node_engineering -.->|"requests AI"| node_gemini
node_engineering -.->|"persists data"| node_database
node_decisions -.->|"validates input"| node_validation
node_decisions -.->|"authenticates"| node_authroute
node_decisions -.->|"requests AI"| node_gemini
node_decisions -.->|"persists data"| node_database
node_authroute -->|"gets provider"| node_authfactory
node_authroute -->|"enforces limit"| node_ratelimit
node_authfactory -->|"selects provider"| node_devauth
node_authfactory -->|"selects provider"| node_firebaseauth
node_gemini -->|"retries calls"| node_retry
node_gemini -->|"validates tools"| node_toolselection
node_evals -.->|"scores runs"| node_scorers
node_scorers -->|"uses similarity"| node_embedding
node_gemini -->|"logs calls"| node_observability
node_copilot -->|"evaluated by"| node_evals
node_documents -->|"evaluated by"| node_evals
node_voice -->|"evaluated by"| node_evals
node_engineering -->|"evaluated by"| node_evals
node_decisions -->|"evaluated by"| node_evals

click node_portalpage "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/apps/portal/src/app/page.tsx"
click node_catalogue "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/apps/portal/src/lib/catalogue.ts"
click node_projectcard "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/apps/portal/src/components/ProjectCard.tsx"
click node_statuspanel "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/apps/portal/src/components/ServerStatusPanel.tsx"
click node_copilot "https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/projects/01-knowledge-copilot"
click node_documents "https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/projects/02-document-intelligence"
click node_voice "https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/projects/03-india-voice-assistant"
click node_engineering "https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/projects/04-engineering-agent"
click node_decisions "https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/projects/05-data-decision-assistant"
click node_validation "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/validation/src/upload.ts"
click node_authroute "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/auth/src/route.ts"
click node_authfactory "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/auth/src/factory.ts"
click node_devauth "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/auth/src/dev-provider.ts"
click node_firebaseauth "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/auth/src/firebase-provider.ts"
click node_ratelimit "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/auth/src/rate-limit.ts"
click node_database "https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/packages/database/src"
click node_gemini "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/ai/src/providers/gemini.ts"
click node_embedding "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/ai/src/embedding.ts"
click node_retry "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/ai/src/retry.ts"
click node_toolselection "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/ai/src/tool-selection.ts"
click node_evals "https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/packages/ai/src/eval"
click node_scorers "https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/ai/src/eval/scorers.ts"
click node_observability "https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/packages/observability/src"
click node_ui "https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/packages/ui/src/components"
click node_shared "https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/packages/shared/src"

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_portalpage,node_catalogue,node_projectcard,node_statuspanel toneBlue
class node_copilot,node_documents,node_voice,node_engineering,node_decisions toneAmber
class node_validation,node_authroute,node_authfactory,node_devauth,node_firebaseauth,node_ratelimit,node_database toneMint
class node_gemini,node_embedding,node_retry,node_toolselection,node_evals,node_scorers toneRose
class node_observability,node_ui,node_shared,node_learner toneIndigo
```

## Components

### Catalogue portal

- [Catalogue page](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/apps/portal/src/app/page.tsx): `apps/portal/src/app/page.tsx`
- [Project catalogue](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/apps/portal/src/lib/catalogue.ts): `apps/portal/src/lib/catalogue.ts`
- [Project cards](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/apps/portal/src/components/ProjectCard.tsx): `apps/portal/src/components/ProjectCard.tsx`
- [Server status](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/apps/portal/src/components/ServerStatusPanel.tsx): `apps/portal/src/components/ServerStatusPanel.tsx`

### Learning projects

- [Knowledge copilot](https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/projects/01-knowledge-copilot): `projects/01-knowledge-copilot`
- [Document intelligence](https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/projects/02-document-intelligence): `projects/02-document-intelligence`
- [Voice assistant](https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/projects/03-india-voice-assistant): `projects/03-india-voice-assistant`
- [Engineering agent](https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/projects/04-engineering-agent): `projects/04-engineering-agent`
- [Decision assistant](https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/projects/05-data-decision-assistant): `projects/05-data-decision-assistant`

### Application boundaries

- [Input validation](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/validation/src/upload.ts): `packages/validation/src/upload.ts`
- [Authenticated routes](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/auth/src/route.ts): `packages/auth/src/route.ts`
- [Auth selection](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/auth/src/factory.ts): `packages/auth/src/factory.ts`
- [Development auth](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/auth/src/dev-provider.ts): `packages/auth/src/dev-provider.ts`
- [Firebase auth](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/auth/src/firebase-provider.ts): `packages/auth/src/firebase-provider.ts`
- [Rate limiting](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/auth/src/rate-limit.ts): `packages/auth/src/rate-limit.ts`
- [Database adapters](https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/packages/database/src): `packages/database/src`

### AI and evaluation

- [Gemini provider](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/ai/src/providers/gemini.ts): `packages/ai/src/providers/gemini.ts`
- [Mock embeddings](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/ai/src/embedding.ts): `packages/ai/src/embedding.ts`
- [Retry policy](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/ai/src/retry.ts): `packages/ai/src/retry.ts`
- [Tool selection](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/ai/src/tool-selection.ts): `packages/ai/src/tool-selection.ts`
- [Evaluation framework](https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/packages/ai/src/eval): `packages/ai/src/eval`
- [Evaluation scorers](https://github.com/tktarun03/beyond-obvious-ai-student-lab/blob/main/packages/ai/src/eval/scorers.ts): `packages/ai/src/eval/scorers.ts`

### Shared foundation

- [Observability](https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/packages/observability/src): `packages/observability/src`
- [Shared UI primitives](https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/packages/ui/src/components): `packages/ui/src/components`
- [Shared utilities](https://github.com/tktarun03/beyond-obvious-ai-student-lab/tree/main/packages/shared/src): `packages/shared/src`

### Other components

- **Learner**

## Connections

- Learner → Catalogue page: opens (evidence: `README.md`)
- Catalogue page → Project catalogue: reads (evidence: `apps/portal/src/app/page.tsx`)
- Catalogue page → Project cards: renders (evidence: `apps/portal/src/app/page.tsx`)
- Catalogue page → Server status: renders (evidence: `apps/portal/src/app/page.tsx`)
- Project cards → Project catalogue: uses data (evidence: `apps/portal/src/components/ProjectCard.tsx`)
- Server status → Knowledge copilot: checks status (evidence: `apps/portal/src/components/ServerStatusPanel.tsx`)
- Server status → Document intelligence: checks status (evidence: `apps/portal/src/components/ServerStatusPanel.tsx`)
- Server status → Voice assistant: checks status (evidence: `apps/portal/src/components/ServerStatusPanel.tsx`)
- Server status → Engineering agent: checks status (evidence: `apps/portal/src/components/ServerStatusPanel.tsx`)
- Server status → Decision assistant: checks status (evidence: `apps/portal/src/components/ServerStatusPanel.tsx`)
- Catalogue page → Shared UI primitives: uses components (evidence: `apps/portal/src/app/page.tsx`)
- Project cards → Shared UI primitives: uses components (evidence: `apps/portal/src/components/ProjectCard.tsx`)
- Knowledge copilot → Input validation: validates input (evidence: `README.md`)
- Knowledge copilot → Authenticated routes: authenticates (evidence: `README.md`)
- Knowledge copilot → Gemini provider: requests AI (evidence: `README.md`)
- Knowledge copilot → Database adapters: persists data (evidence: `README.md`)
- Document intelligence → Input validation: validates input (evidence: `README.md`)
- Document intelligence → Authenticated routes: authenticates (evidence: `README.md`)
- Document intelligence → Gemini provider: requests AI (evidence: `README.md`)
- Document intelligence → Database adapters: persists data (evidence: `README.md`)
- Voice assistant → Input validation: validates input (evidence: `README.md`)
- Voice assistant → Authenticated routes: authenticates (evidence: `README.md`)
- Voice assistant → Gemini provider: requests AI (evidence: `README.md`)
- Voice assistant → Database adapters: persists data (evidence: `README.md`)
- Engineering agent → Input validation: validates input (evidence: `README.md`)
- Engineering agent → Authenticated routes: authenticates (evidence: `README.md`)
- Engineering agent → Gemini provider: requests AI (evidence: `README.md`)
- Engineering agent → Database adapters: persists data (evidence: `README.md`)
- Decision assistant → Input validation: validates input (evidence: `README.md`)
- Decision assistant → Authenticated routes: authenticates (evidence: `README.md`)
- Decision assistant → Gemini provider: requests AI (evidence: `README.md`)
- Decision assistant → Database adapters: persists data (evidence: `README.md`)
- Authenticated routes → Auth selection: gets provider (evidence: `packages/auth/src/route.ts`)
- Authenticated routes → Rate limiting: enforces limit (evidence: `packages/auth/src/route.ts`)
- Auth selection → Development auth: selects provider (evidence: `packages/auth/src/factory.ts`)
- Auth selection → Firebase auth: selects provider (evidence: `packages/auth/src/factory.ts`)
- Gemini provider → Retry policy: retries calls (evidence: `packages/ai/src/providers/gemini.ts`)
- Gemini provider → Tool selection: validates tools (evidence: `packages/ai/src/providers/gemini.ts`)
- Evaluation framework → Evaluation scorers: scores runs (evidence: `packages/ai/src/eval/scorers.ts`)
- Evaluation scorers → Mock embeddings: uses similarity (evidence: `packages/ai/src/eval/scorers.ts`)
- Gemini provider → Observability: logs calls (evidence: `packages/ai/src/providers/gemini.ts`)
- Knowledge copilot → Evaluation framework: evaluated by (evidence: `projects/01-knowledge-copilot/evals/run.ts`)
- Document intelligence → Evaluation framework: evaluated by (evidence: `projects/02-document-intelligence/evals/run.ts`)
- Voice assistant → Evaluation framework: evaluated by (evidence: `projects/03-india-voice-assistant/evals/run.ts`)
- Engineering agent → Evaluation framework: evaluated by (evidence: `projects/04-engineering-agent/evals/run.ts`)
- Decision assistant → Evaluation framework: evaluated by (evidence: `projects/05-data-decision-assistant/evals/run.ts`)
