Merge pull request #10 from NicholasGoh/feat/revamp-fastapi-mcp-langgraph-template-docs

Feat/revamp fastapi mcp langgraph template docs

Author: NicholasGoh

docs/getting-started/_category_.json

@@ -3,6 +3,6 @@
   "position": 2,
   "link": {
     "type": "generated-index",
-    "description": "5 minutes to learn the most important Docusaurus concepts."
+    "description": "Check out more about the template or jump to the quick start to get it set up and give it a try!"
   }
 }

docs/getting-started/architecture.mdx

@@ -0,0 +1,104 @@
+---
+sidebar_position: 1
+---
+
+# Architecture
+
+This section outlines the architecture of the services, their interactions, and planned features.
+
+## Inspector
+
+Inspector communicates via SSE protocol with each MCP Server, while each server adheres to MCP specification.
+
+```mermaid
+graph LR
+
+  subgraph localhost
+    A[Inspector]
+    B[DBHub Server]
+    C[Youtube Server]
+    D[Custom Server]
+  end
+
+  subgraph Supabase Cloud
+    E[Supabase DB]
+  end
+
+  subgraph Google Cloud
+    F[Youtube API]
+  end
+
+  A<-->|Protocol|B
+  A<-->|Protocol|C
+  A<-->|Protocol|D
+  B<-->E
+  C<-->F
+```
+
+## Template Setup
+
+The current template does not connect to all MCP servers. Additionally, the API server communicates with the database using a SQL ORM.
+
+```mermaid
+graph LR
+
+  subgraph localhost
+    A[API Server]
+    B[DBHub Server]
+    C[Youtube Server]
+    D[Custom Server]
+  end
+
+  subgraph Supabase Cloud
+    E[Supabase DB]
+  end
+
+  A<-->|Protocol|D
+  A<-->E
+```
+
+## Reverse Proxy
+
+Can be extended for other services like Frontend and/or certain backend services self-hosted instead of on cloud (e.g., Langfuse).
+
+```mermaid
+graph LR
+  A[Web Browser]
+
+  subgraph localhost
+    B[Nginx Reverse Proxy]
+    C[API Server]
+  end
+
+  A-->B
+  B-->C
+```
+
+## Planned Features
+
+### Monitoring and Observability
+
+```mermaid
+graph LR
+
+  subgraph localhost
+    A[API Server]
+  end
+
+  subgraph Grafana Cloud
+    B[Grafana]
+  end
+
+  subgraph Langfuse Cloud
+    C[Langfuse]
+  end
+
+  A -->|Metrics & Logs| B
+  A -->|Traces & Events| C
+```
+
+### Authentication and Authorization
+
+![Auth0 Diagram](https://images.ctfassets.net/cdy7uua7fh8z/7mWk9No612EefC8uBidCqr/821eb60b0aa953b0d8e4afe897228844/Auth-code-flow-diagram.png)
+
+[Auth0 Source](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)

docs/getting-started/grafana-stack.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 7
+---
+
+# Grafana Stack
+
+> By configuring the OpenAI Integration, users can gain valuable insights into token usage rates, response times, and overall costs. This integration empowers users to make data-driven decisions while ensuring optimal utilization of OpenAI APIs.
+
+Learn more [here](https://grafana.com/docs/grafana-cloud/monitor-infrastructure/integrations/integration-reference/integration-openai/)
+
+[![Grafana](https://img.shields.io/github/stars/prometheus/prometheus?logo=grafana&label=Grafana)](https://github.com/grafana/grafana)

docs/getting-started/langfuse.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 6
+---
+
+# Langfuse
+
+> Traces, evals, prompt management and metrics to debug and improve your LLM application.
+
+Learn more [here](https://langfuse.com/)
+
+[![LangFuse](https://img.shields.io/github/stars/langfuse/langfuse?logo=langfuse&label=LangFuse)](https://github.com/langfuse/langfuse)

docs/getting-started/langgraph.mdx

@@ -0,0 +1,19 @@
+---
+sidebar_position: 4
+---
+
+# LangGraph
+
+> Gain control with LangGraph to design agents that reliably handle complex tasks.
+
+Learn more [here](https://www.langchain.com/langgraph)
+
+[![LangGraph](https://img.shields.io/github/stars/langchain-ai/langgraph?logo=langgraph&label=LangGraph)](https://github.com/langchain-ai/langgraph)
+
+## Streaming
+
+At its core, a compiled LangGraph is a [Runnable](https://github.com/langchain-ai/langchain/blob/langchain%3D%3D0.3.6/libs/core/langchain_core/runnables/base.py#L108). This template utilizes LangChain’s built-in streaming support through [`astream_events`](https://python.langchain.com/docs/how_to/streaming/#using-stream-events), granting programmatic access to every stage of the Agentic Workflow. You can observe and interact with key components—LLM, prompt, and tool—throughout their full execution lifecycle: start, stream, and end. For a comprehensive list of event types and usage examples, refer to the [Event Reference](https://python.langchain.com/docs/how_to/streaming/#event-reference).
+
+## Persistence
+
+LangGraph offers built-in state management and persistence via the [AsyncPostgresSaver](https://github.com/langchain-ai/langgraph/blob/0.2.39/libs/checkpoint-postgres/langgraph/checkpoint/postgres/aio.py#L39), enabling faster iteration on agentic workflows. Since LLMs are inherently stateless, chat history must typically be injected as context for each query—but LangGraph abstracts this away, requiring only a `thread_id`. It seamlessly handles chat history and metadata serialization/deserialization, simplifying development. Learn more about its advanced persistence capabilities [here](https://langchain-ai.github.io/langgraph/concepts/persistence/).

docs/getting-started/model-context-protocol.mdx

@@ -1,13 +1,11 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 import ReactPlayer from 'react-player'
 
 # Model Context Protocol
 
-[![MCP Client](https://img.shields.io/github/stars/modelcontextprotocol/python-sdk?logo=modelcontextprotocol&label=MCP-Client)](https://github.com/modelcontextprotocol/python-sdk) [![MCP Server](https://img.shields.io/github/stars/modelcontextprotocol/servers?logo=modelcontextprotocol&label=MCP-Servers)](https://github.com/modelcontextprotocol/servers)
-
 :::info
 
 > MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.
@@ -16,6 +14,8 @@ import ReactPlayer from 'react-player'
 
 Learn more [here](https://modelcontextprotocol.io/introduction).
 
+[![MCP Client](https://img.shields.io/github/stars/modelcontextprotocol/python-sdk?logo=modelcontextprotocol&label=MCP-Client)](https://github.com/modelcontextprotocol/python-sdk) [![MCP Server](https://img.shields.io/github/stars/modelcontextprotocol/servers?logo=modelcontextprotocol&label=MCP-Servers)](https://github.com/modelcontextprotocol/servers)
+
 ## Video Demo
 
 <ReactPlayer playing controls url='/vid/fastapi-mcp-langgraph-template/mcps.mp4' />
@@ -43,6 +43,8 @@ Explore the following tabs in the Top Navbar:
 - `Prompts`
 - `Tools`
 
+See demo videos to learn more.
+
 ## Community MCP Servers
 
 Before building your own custom MCP servers, explore the growing list of hundreds of [community MCP servers](https://github.com/modelcontextprotocol/servers). With integrations spanning databases, cloud services, and web resources, the perfect fit might already exist.
@@ -54,14 +56,34 @@ Learn more [here](https://github.com/bytebase/dbhub). Explore more in [Inspector
 Easily plug in this MCP into LLM to allow LLM to:
 
 - Perform read-only SQL query validation for secure operations
+
+<ReactPlayer playing controls url='/vid/fastapi-mcp-langgraph-template/dbhub/execute-sql.mp4' />
+
+<br />
+
 - Enable deterministic introspection of DB
   - List schemas
   - List tables in schemas
   - Retrieve table structures
+
+<ReactPlayer playing controls url='/vid/fastapi-mcp-langgraph-template/dbhub/schemas.mp4' />
+
+<br />
+
 - Enrich user queries deterministically
   - Ground DB related queries with DB schemas
   - Provide SQL templates for translating natural language to SQL
 
+<ReactPlayer playing controls url='/vid/fastapi-mcp-langgraph-template/dbhub/explain-db.mp4' />
+
+<br />
+
+:::info
+
+Demos only show some features; all features are not shown exhaustively in the videos
+
+:::
+
 ### Youtube
 
 Learn more [here](https://github.com/Klavis-AI/klavis/tree/main/mcp_servers/youtube). Explore more in [Inspector](#inspector).
@@ -77,6 +99,8 @@ Simply plug in this MCP to enable LLM to:
 
 - Fetch transcripts from any YouTube URL on demand
 
+Check out the [demo video](#video-demo) at the top.
+
 ## Custom MCP
 
 Should you require a custom MCP server, a template is provided [here](https://github.com/NicholasGoh/fastapi-mcp-langgraph-template/blob/main/backend/shared_mcp/tools.py) for you to reference in development.
@@ -103,3 +127,5 @@ def get_greeting(name: str) -> str:
     """Get a personalized greeting"""
     return f"Hello, {name}!"
 ```
+
+Check out the [demo video](#video-demo) at the top.

docs/getting-started/quick-start.mdx

@@ -1,11 +1,13 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 ---
 
 import ReactPlayer from 'react-player'
 
 # Quick Start
 
+Setup to run the repository in both production and development environments.
+
 Build community youtube MCP image with:
 
 ```bash

docs/getting-started/supabase.mdx

@@ -1,11 +1,13 @@
 ---
-sidebar_position: 3
+sidebar_position: 5
 ---
 
 import ReactPlayer from 'react-player'
 
 # Supabase
 
+Demo on getting `POSTGRES_DSN` with Supabase’s free database, auth, and APIs.
+
 [![Supabase](https://img.shields.io/github/stars/supabase/supabase?logo=supabase&label=Supabase)](https://github.com/supabase/supabase)
 
 The start of the video shows how you can get your `POSTGRES_DSN` URL.

docs/intro.mdx

@@ -7,7 +7,7 @@ title: Introduction
 
 A modern template for agentic orchestration — built for rapid iteration and scalable deployment using highly customizable, community-supported tools like MCP, LangGraph, and more.
 
-Visit the [Github](https://github.com/NicholasGoh/fastapi-mcp-langgraph-template)
+Visit the Github: [![FastAPI MCP LangGraph Template](https://img.shields.io/github/stars/nicholasgoh/fastapi-mcp-langgraph-template?label=FastAPI%20MCP%20LangGraph%20Template)](https://github.com/NicholasGoh/fastapi-mcp-langgraph-template)
 
 ## Core Features
 
@@ -36,8 +36,18 @@ Visit the [Github](https://github.com/NicholasGoh/fastapi-mcp-langgraph-template
 - [![LangFuse](https://img.shields.io/github/stars/langfuse/langfuse?logo=langfuse&label=LangFuse)](https://github.com/langfuse/langfuse) for LLM Observability and LLM Metrics
 - [![Prometheus](https://img.shields.io/github/stars/prometheus/prometheus?logo=prometheus&label=Prometheus)](https://github.com/prometheus/prometheus) for scraping Metrics
 - [![Grafana](https://img.shields.io/github/stars/prometheus/prometheus?logo=grafana&label=Grafana)](https://github.com/grafana/grafana) for visualizing Metrics
-- [![Auth0](https://img.shields.io/badge/Auth0-white?logo=auth0)](https://auth0.com/docs) SaaS for JWT authentication
+- [![Auth0](https://img.shields.io/badge/Auth0-white?logo=auth0)](https://auth0.com/docs) SaaS for Authentication and Authorization with OIDC & JWT via OAuth 2.0
 - CI/CD via Github Actions
   - :dollar: Deploy live demo to [![Fargate](https://img.shields.io/badge/Fargate-white.svg?logo=awsfargate)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html)
   - Provision with [![Terraform](https://img.shields.io/github/stars/hashicorp/terraform?logo=terraform&label=Terraform)](https://github.com/hashicorp/terraform) IaC
   - Push built images to ECR and Dockerhub
+
+[![Star History Chart](https://api.star-history.com/svg?repos=nicholasgoh/fastapi-mcp-langgraph-template&type=Date)](https://www.star-history.com/#nicholasgoh/fastapi-mcp-langgraph-template&Date)
+
+:::info
+
+Click above to view live update on star history as per their [article](https://www.star-history.com/blog/a-message-to-github-star-history-users):
+> Ongoing Broken Live Chart
+> you can still use this website to view and download charts (though you may need to provide your own token).
+
+:::