# guochen-thlg/ai-fullstack-entrance-exam architecture

> Architecture diagram of the GitHub repository guochen-thlg/ai-fullstack-entrance-exam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guochen-thlg/ai-fullstack-entrance-exam
- Repository: https://github.com/guochen-thlg/ai-fullstack-entrance-exam

## Overview

This repository contains two AsterVision products: an AI-visibility analytics dashboard and a product knowledge center. The dashboard workflow runs from overview or question analysis in the React app through its hooks and API client to Koa, which reads summary/question data and serves filtered results or computed mock insights. The knowledge center serves product/FAQ content, supports rule-based knowledge Q&A and product administration, and exposes read-only tools to browser agents. README documentation supplies several unsampled capabilities; those are represented at their documented source paths, with uncertain implementation wiring omitted.

Main entry points: [`apps/project1-dashboard/web/src/App.tsx`](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/App.tsx) (Dashboard app), [`apps/project2-knowledge/src/lib/data.ts`](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/lib/data.ts) (Knowledge data layer), [`apps/project2-knowledge/src/components/WebMcpTools.tsx`](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/components/WebMcpTools.tsx) (WebMCP tools), [`apps/project1-dashboard/server/src/app.ts`](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/server/src/app.ts) (Koa API app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_p1web["Dashboard interface"]
  node_p1app["Dashboard app<br/>[App.tsx]"]
  node_p1filters["Filter state"]
  node_p1summary["Summary loading<br/>[useSummary.ts]"]
  node_p1list["Question loading<br/>[useQuestionList.ts]"]
  node_p1insighthook["Insight state<br/>[useInsight.ts]"]
  node_p1visuals["Dashboard visuals<br/>[TrendChart.tsx]"]
  node_p1questions["Question views<br/>[QuestionTable.tsx]"]
  node_p1client["Dashboard API client<br/>[dashboard.ts]"]
end

subgraph group_p1api["Dashboard API"]
  node_p1server["Koa API app<br/>[app.ts]"]
  node_p1source["Cached data source<br/>[dataSource.ts]"]
  node_p1questionservice["Question queries<br/>[questionService.ts]"]
  node_p1insightservice["Insight rules<br/>[insightService.ts]"]
  node_p1json[("Dashboard JSON data")]
end

subgraph group_p2site["Knowledge experience"]
  node_p2home["Knowledge home<br/>[page.tsx]"]
  node_p2products["Product pages<br/>[page.tsx]"]
  node_p2detail["Product detail<br/>[page.tsx]"]
  node_p2faq["FAQ page<br/>[page.tsx]"]
  node_p2admin["Product admin<br/>[page.tsx]"]
  node_p2askwidget["Ask AI widget<br/>[AskAIWidget.tsx]"]
  node_p2webmcp["WebMCP tools<br/>[WebMcpTools.tsx]"]
  node_p2seo["SEO metadata<br/>[sitemap.ts]"]
end

subgraph group_p2api["Knowledge API"]
  node_p2askroute["Ask endpoint<br/>[route.ts]"]
  node_p2productsroute["Product endpoints<br/>[route.ts]"]
  node_p2slugroute["Product detail endpoint<br/>[route.ts]"]
end

subgraph group_p2core["Knowledge services"]
  node_p2data["Knowledge data layer<br/>[data.ts]"]
  node_p2ask["Knowledge retrieval<br/>[ask.ts]"]
  node_p2webmcplib["Tool definitions<br/>[webmcp.ts]"]
  node_p2json[("Knowledge JSON files")]
end

node_visitor(("Site visitor"))
node_agent(("Browser AI agent"))

node_visitor -->|"uses"| node_p1app
node_p1app -->|"loads"| node_p1summary
node_p1app -->|"updates"| node_p1filters
node_p1app -->|"loads"| node_p1list
node_p1app -->|"requests insight"| node_p1insighthook
node_p1app -->|"renders"| node_p1visuals
node_p1app -->|"renders"| node_p1questions
node_p1filters -->|"provides filters"| node_p1list
node_p1summary -->|"requests summary"| node_p1client
node_p1list -->|"requests questions"| node_p1client
node_p1insighthook -->|"requests insight"| node_p1client
node_p1client -->|"HTTP requests"| node_p1server
node_p1server -->|"loads summary/questions"| node_p1source
node_p1server -->|"queries questions"| node_p1questionservice
node_p1server -->|"generates insight"| node_p1insightservice
node_p1source -->|"reads"| node_p1json
node_p2home -->|"reads content"| node_p2data
node_p2products -->|"reads products"| node_p2data
node_p2detail -->|"reads detail"| node_p2data
node_p2faq -->|"reads FAQs"| node_p2data
node_p2admin -->|"manages products"| node_p2productsroute
node_p2askwidget -->|"asks question"| node_p2askroute
node_p2askroute -->|"retrieves answer"| node_p2ask
node_p2ask -->|"searches knowledge"| node_p2data
node_p2productsroute -->|"reads/writes products"| node_p2data
node_p2slugroute -->|"reads/updates product"| node_p2data
node_p2data -->|"reads/writes"| node_p2json
node_p2webmcp -->|"registers tools"| node_p2webmcplib
node_agent -.->|"invokes tools"| node_p2webmcp
node_p2webmcp -.->|"fetches product"| node_p2slugroute
node_p2webmcp -.->|"searches products"| node_p2productsroute
node_p2webmcp -.->|"asks knowledge"| node_p2askroute
node_p2home -->|"publishes site metadata"| node_p2seo

click node_p1app "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/App.tsx"
click node_p1filters "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/hooks/useQuestionFilters.ts"
click node_p1summary "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/hooks/useSummary.ts"
click node_p1list "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/hooks/useQuestionList.ts"
click node_p1insighthook "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/hooks/useInsight.ts"
click node_p1visuals "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/components/dashboard/TrendChart.tsx"
click node_p1questions "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/components/questions/QuestionTable.tsx"
click node_p1client "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/api/dashboard.ts"
click node_p1server "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/server/src/app.ts"
click node_p1source "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/server/src/dataSource.ts"
click node_p1questionservice "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/server/src/services/questionService.ts"
click node_p1insightservice "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/server/src/services/insightService.ts"
click node_p2home "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/page.tsx"
click node_p2products "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/products/page.tsx"
click node_p2detail "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/products/%5Bslug%5D/page.tsx"
click node_p2faq "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/faq/page.tsx"
click node_p2admin "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/admin/products/page.tsx"
click node_p2askwidget "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/components/AskAIWidget.tsx"
click node_p2webmcp "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/components/WebMcpTools.tsx"
click node_p2seo "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/sitemap.ts"
click node_p2askroute "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/api/ask/route.ts"
click node_p2productsroute "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/api/products/route.ts"
click node_p2slugroute "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/api/products/%5Bslug%5D/route.ts"
click node_p2data "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/lib/data.ts"
click node_p2ask "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/lib/ask.ts"
click node_p2webmcplib "https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/lib/webmcp.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_p1app,node_p1filters,node_p1summary,node_p1list,node_p1insighthook,node_p1visuals,node_p1questions,node_p1client,node_agent toneBlue
class node_p1server,node_p1source,node_p1questionservice,node_p1insightservice,node_p1json toneAmber
class node_p2home,node_p2products,node_p2detail,node_p2faq,node_p2admin,node_p2askwidget,node_p2webmcp,node_p2seo toneMint
class node_p2askroute,node_p2productsroute,node_p2slugroute toneRose
class node_p2data,node_p2ask,node_p2webmcplib,node_p2json,node_visitor toneIndigo
```

## Components

### Dashboard interface

- [Dashboard app](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/App.tsx): `apps/project1-dashboard/web/src/App.tsx`
- [Filter state](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/hooks/useQuestionFilters.ts): `apps/project1-dashboard/web/src/hooks/useQuestionFilters.ts`
- [Summary loading](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/hooks/useSummary.ts): `apps/project1-dashboard/web/src/hooks/useSummary.ts`
- [Question loading](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/hooks/useQuestionList.ts): `apps/project1-dashboard/web/src/hooks/useQuestionList.ts`
- [Insight state](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/hooks/useInsight.ts): `apps/project1-dashboard/web/src/hooks/useInsight.ts`
- [Dashboard visuals](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/components/dashboard/TrendChart.tsx): `apps/project1-dashboard/web/src/components/dashboard/TrendChart.tsx`
- [Question views](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/components/questions/QuestionTable.tsx): `apps/project1-dashboard/web/src/components/questions/QuestionTable.tsx`
- [Dashboard API client](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/web/src/api/dashboard.ts): `apps/project1-dashboard/web/src/api/dashboard.ts`

### Dashboard API

- [Koa API app](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/server/src/app.ts): `apps/project1-dashboard/server/src/app.ts`
- [Cached data source](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/server/src/dataSource.ts): `apps/project1-dashboard/server/src/dataSource.ts`
- [Question queries](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/server/src/services/questionService.ts): `apps/project1-dashboard/server/src/services/questionService.ts`
- [Insight rules](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project1-dashboard/server/src/services/insightService.ts): `apps/project1-dashboard/server/src/services/insightService.ts`
- **Dashboard JSON data**

### Knowledge experience

- [Knowledge home](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/page.tsx): `apps/project2-knowledge/src/app/page.tsx`
- [Product pages](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/products/page.tsx): `apps/project2-knowledge/src/app/products/page.tsx`
- [Product detail](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/products/%5Bslug%5D/page.tsx): `apps/project2-knowledge/src/app/products/[slug]/page.tsx`
- [FAQ page](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/faq/page.tsx): `apps/project2-knowledge/src/app/faq/page.tsx`
- [Product admin](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/admin/products/page.tsx): `apps/project2-knowledge/src/app/admin/products/page.tsx`
- [Ask AI widget](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/components/AskAIWidget.tsx): `apps/project2-knowledge/src/components/AskAIWidget.tsx`
- [WebMCP tools](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/components/WebMcpTools.tsx): `apps/project2-knowledge/src/components/WebMcpTools.tsx`
- [SEO metadata](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/sitemap.ts): `apps/project2-knowledge/src/app/sitemap.ts`

### Knowledge API

- [Ask endpoint](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/api/ask/route.ts): `apps/project2-knowledge/src/app/api/ask/route.ts`
- [Product endpoints](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/api/products/route.ts): `apps/project2-knowledge/src/app/api/products/route.ts`
- [Product detail endpoint](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/app/api/products/%5Bslug%5D/route.ts): `apps/project2-knowledge/src/app/api/products/[slug]/route.ts`

### Knowledge services

- [Knowledge data layer](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/lib/data.ts): `apps/project2-knowledge/src/lib/data.ts`
- [Knowledge retrieval](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/lib/ask.ts): `apps/project2-knowledge/src/lib/ask.ts`
- [Tool definitions](https://github.com/guochen-thlg/ai-fullstack-entrance-exam/blob/main/apps/project2-knowledge/src/lib/webmcp.ts): `apps/project2-knowledge/src/lib/webmcp.ts`
- **Knowledge JSON files**

### Other components

- **Site visitor**
- **Browser AI agent**

## Connections

- Site visitor → Dashboard app: uses
- Dashboard app → Summary loading: loads
- Dashboard app → Filter state: updates
- Dashboard app → Question loading: loads
- Dashboard app → Insight state: requests insight
- Dashboard app → Dashboard visuals: renders
- Dashboard app → Question views: renders
- Filter state → Question loading: provides filters
- Summary loading → Dashboard API client: requests summary
- Question loading → Dashboard API client: requests questions
- Insight state → Dashboard API client: requests insight
- Dashboard API client → Koa API app: HTTP requests
- Koa API app → Cached data source: loads summary/questions
- Koa API app → Question queries: queries questions
- Koa API app → Insight rules: generates insight
- Cached data source → Dashboard JSON data: reads
- Knowledge home → Knowledge data layer: reads content
- Product pages → Knowledge data layer: reads products
- Product detail → Knowledge data layer: reads detail
- FAQ page → Knowledge data layer: reads FAQs
- Product admin → Product endpoints: manages products
- Ask AI widget → Ask endpoint: asks question
- Ask endpoint → Knowledge retrieval: retrieves answer
- Knowledge retrieval → Knowledge data layer: searches knowledge
- Product endpoints → Knowledge data layer: reads/writes products
- Product detail endpoint → Knowledge data layer: reads/updates product
- Knowledge data layer → Knowledge JSON files: reads/writes
- WebMCP tools → Tool definitions: registers tools
- Browser AI agent → WebMCP tools: invokes tools
- WebMCP tools → Product detail endpoint: fetches product
- WebMCP tools → Product endpoints: searches products
- WebMCP tools → Ask endpoint: asks knowledge
- Knowledge home → SEO metadata: publishes site metadata