Modern Python Web Stack 2025: FastAPI + React + Tailwind for Real-World Applications

Every few years, the “best” web stack changes. In 2025, here’s what we’re using for AI-powered applications:

Backend: FastAPI (Python) Frontend: React + TypeScript + Vite Styling: Tailwind CSS v4 + shadcn/ui State: React Query

This isn’t theoretical. We built a complete YouTube-to-Obsidian pipeline with this stack - 50+ API endpoints, real-time progress updates, background job processing, and a polished UI. Here’s what we learned.

The Architecture#

Figure 1 - Full-stack architecture diagram showing the layered structure: React frontend with components and React Query, API layer with FastAPI endpoints, backend services connecting to PostgreSQL, Qdrant, and Anthropic API

The architecture follows a clean separation of concerns:

Frontend: React components → React Query → Fetch API
Backend: FastAPI routers → Services → Repositories
Data: PostgreSQL (relational) + Qdrant (vectors) + External APIs

Part 1: FastAPI Backend#

Why FastAPI?#

After years of Flask and Django, FastAPI feels like a revelation:

Type hints everywhere - Pydantic models for request/response validation
Auto-generated docs - Swagger UI at /docs for free
Async-first - Native async/await support
Fast - Built on Starlette and Uvicorn

Project Structure#

1
api/
2
├── main.py           # FastAPI app, CORS, routers
3
├── models.py         # Pydantic request/response models
4
├── jobs.py           # Background job management
5
├── youtube_batch.py  # YouTube processing service
6
├── vault_batch.py    # Vault processing service
7
└── repositories/     # Database access layer
8
    ├── tags.py
9
    ├── notes.py
10
    └── batches.py

The Main App#

1
from fastapi import FastAPI
2
from fastapi.middleware.cors import CORSMiddleware
3

4
app = FastAPI(
5
    title="YouTube Markdown Agent",
6
    description="Convert YouTube videos to Obsidian notes",
7
    version="1.0.0",
8
)
9

10
# CORS for local development
11
app.add_middleware(
12
    CORSMiddleware,
13
    allow_origins=["http://localhost:5173", "http://localhost:5174"],
14
    allow_credentials=True,
15
    allow_methods=["*"],
16
    allow_headers=["*"],
17
)

Request/Response Models#

Pydantic models define your API contract:

1
from pydantic import BaseModel
2
from typing import Optional
3
from enum import Enum
4

5
class ProcessingMode(str, Enum):
6
    SUMMARY = "summary"
7
    DETAILED = "detailed"
8

9
class YouTubeRequest(BaseModel):
10
    urls: list[str]
11
    mode: ProcessingMode = ProcessingMode.SUMMARY
12

13
class ProcessingStatus(BaseModel):
14
    job_id: str
15
    status: str  # "pending", "processing", "completed", "failed"
16
    progress: int  # 0-100
17
    current_step: Optional[str] = None
18
    results: Optional[list[dict]] = None
19

20
class YouTubeResponse(BaseModel):
21
    job_id: str
22
    mode: str  # "sync" or "batch"
23
    status: ProcessingStatus

FastAPI validates requests automatically. Send invalid JSON, get a clear error message. No manual parsing needed.

Endpoint Patterns#

Processing endpoint:

1
@app.post("/api/youtube/process", response_model=YouTubeResponse)
2
async def process_youtube(request: YouTubeRequest):
3
    """Process YouTube videos."""
4

5
    if len(request.urls) == 1:
6
        # Single video: sync processing
7
        result = await process_single_video(request.urls[0], request.mode)
8
        return YouTubeResponse(
9
            job_id="sync",
10
            mode="sync",
11
            status=ProcessingStatus(
12
                job_id="sync",
13
                status="completed",
14
                progress=100,
15
                results=[result],
16
            ),
17
        )
18
    else:
19
        # Multiple videos: batch processing
20
        job_id = create_batch_job(request.urls, request.mode)
21
        return YouTubeResponse(
22
            job_id=job_id,
23
            mode="batch",
24
            status=ProcessingStatus(
25
                job_id=job_id,
26
                status="pending",
27
                progress=0,
28
            ),
29
        )

Status endpoint:

1
@app.get("/api/youtube/status/{job_id}", response_model=ProcessingStatus)
2
async def get_status(job_id: str):
3
    """Get processing status for a job."""
4

5
    job = get_job(job_id)
6

7
    if not job:
8
        raise HTTPException(status_code=404, detail="Job not found")
9

10
    return ProcessingStatus(
11
        job_id=job_id,
12
        status=job.status,
13
        progress=job.progress,
14
        current_step=job.current_step,
15
        results=job.results if job.status == "completed" else None,
16
    )

Background Jobs#

For long-running tasks, we use a simple in-memory job store:

1
from dataclasses import dataclass, field
2
from datetime import datetime
3
from typing import Any
4
import asyncio
5

6
@dataclass
7
class Job:
8
    job_id: str
9
    status: str = "pending"
10
    progress: int = 0
11
    current_step: str = ""
12
    results: list[Any] = field(default_factory=list)
13
    created_at: datetime = field(default_factory=datetime.now)
14

15
# Simple in-memory store (use Redis for production)
16
jobs: dict[str, Job] = {}
17

18
async def run_job(job_id: str, urls: list[str], mode: str):
19
    """Run processing job in background."""
20

21
    job = jobs[job_id]
22
    job.status = "processing"
23

24
    try:
25
        total = len(urls)
26
        for i, url in enumerate(urls):
27
            job.current_step = f"Processing video {i+1}/{total}"
28
            job.progress = int((i / total) * 100)
29

30
            result = await process_single_video(url, mode)
31
            job.results.append(result)
32

33
        job.status = "completed"
34
        job.progress = 100
35

36
    except Exception as e:
37
        job.status = "failed"
38
        job.current_step = str(e)

Figure 2 - Swagger UI documentation screenshot showing the auto-generated API docs at /docs endpoint

Part 2: React Frontend#

Why React + Vite?#

Vite - Instant hot reload, fast builds, native ESM
TypeScript - Catch errors before runtime
React Query - Server state management that just works

Project Structure#

1
frontend/
2
├── src/
3
│   ├── App.tsx              # Main app shell
4
│   ├── main.tsx             # Entry point
5
│   ├── lib/
6
│   │   └── api.ts           # API client
7
│   ├── components/
8
│   │   ├── VideoForm.tsx    # URL input form
9
│   │   ├── VaultFileList.tsx
10
│   │   ├── ProcessingStatus.tsx
11
│   │   └── ui/              # shadcn components
12
│   └── hooks/
13
│       └── useProcessing.ts # Processing logic hook
14
├── tailwind.config.js
15
└── vite.config.ts

The API Client#

Type-safe API calls:

1
const API_BASE = "http://localhost:8000/api";
2

3
export interface YouTubeRequest {
4
  urls: string[];
5
  mode: "summary" | "detailed";
6
}
7

8
export interface ProcessingStatus {
9
  job_id: string;
10
  status: "pending" | "processing" | "completed" | "failed";
11
  progress: number;
12
  current_step?: string;
13
  results?: ProcessingResult[];
14
}
15

16
export async function processYouTube(
17
  request: YouTubeRequest
18
): Promise<YouTubeResponse> {
19
  const response = await fetch(`${API_BASE}/youtube/process`, {
20
    method: "POST",
21
    headers: { "Content-Type": "application/json" },
22
    body: JSON.stringify(request),
23
  });
24

25
  if (!response.ok) {
26
    throw new Error(`API error: ${response.status}`);
27
  }
28

29
  return response.json();
30
}

React Query for Server State#

React Query handles caching, refetching, and loading states:

1
import { useMutation, useQuery } from "@tanstack/react-query";
2
import { processYouTube, getStatus } from "../lib/api";
3

4
export function useProcessYouTube() {
5
  return useMutation({
6
    mutationFn: processYouTube,
7
  });
8
}
9

10
export function useJobStatus(jobId: string | null, enabled: boolean) {
11
  return useQuery({
12
    queryKey: ["job-status", jobId],
13
    queryFn: () => getStatus(jobId!),
14
    enabled: enabled && !!jobId,
15
    refetchInterval: (data) => {
16
      // Poll every 5 seconds until complete
17
      if (data?.status === "completed" || data?.status === "failed") {
18
        return false;
19
      }
20
      return 5000;
21
    },
22
  });
23
}

Usage in components:

1
function ProcessingPanel() {
2
  const [jobId, setJobId] = useState<string | null>(null);
3
  const [isPolling, setIsPolling] = useState(false);
4

5
  const processMutation = useProcessYouTube();
6
  const { data: status } = useJobStatus(jobId, isPolling);
7

8
  async function handleSubmit(urls: string[], mode: string) {
9
    const response = await processMutation.mutateAsync({ urls, mode });
10

11
    if (response.mode === "sync") {
12
      displayResults(response.status.results);
13
    } else {
14
      setJobId(response.job_id);
15
      setIsPolling(true);
16
    }
17
  }
18

19
  useEffect(() => {
20
    if (status?.status === "completed") {
21
      setIsPolling(false);
22
      displayResults(status.results);
23
    }
24
  }, [status]);
25

26
  return (
27
    <div>
28
      <VideoForm onSubmit={handleSubmit} />
29
      {status && <ProgressBar progress={status.progress} />}
30
    </div>
31
  );
32
}

Part 3: Tailwind + shadcn/ui#

Why Tailwind?#

Utility-first - No context switching to CSS files
Consistent - Design tokens built in (spacing, colors, etc.)
Purging - Only ship CSS you actually use
Dark mode - One class to rule them all

Why shadcn/ui?#

shadcn/ui isn’t a component library - it’s a collection of copy-paste components built on Radix UI primitives. You own the code, so you can customize everything.

1
npx shadcn@latest add button
2
npx shadcn@latest add input
3
npx shadcn@latest add card
4
npx shadcn@latest add tabs

This adds the component source to your project. No npm dependency, no version conflicts.

Dark Mode by Default#

We default to dark mode because we have standards:

1
function App() {
2
  return (
3
    <div className="min-h-screen bg-background text-foreground dark">
4
      <AppShell />
5
    </div>
6
  );
7
}

The dark class on a parent element enables dark mode for all children.

Two-Panel Layout#

For productivity apps, the list-detail pattern works well:

1
function AppShell() {
2
  const [selectedItem, setSelectedItem] = useState<Item | null>(null);
3

4
  return (
5
    <div className="flex h-screen">
6
      {/* Left panel: List */}
7
      <div className="w-1/3 border-r border-border overflow-auto">
8
        <ItemList
9
          onSelect={setSelectedItem}
10
          selectedId={selectedItem?.id}
11
        />
12
      </div>
13

14
      {/* Right panel: Detail */}
15
      <div className="flex-1 overflow-auto">
16
        {selectedItem ? (
17
          <ItemDetail item={selectedItem} />
18
        ) : (
19
          <EmptyState message="Select an item to view details" />
20
        )}
21
      </div>
22
    </div>
23
  );
24
}

Figure 3 - Two-panel layout screenshot showing file list on left, detail/preview panel on right, dark theme with teal accents

Component Example: Video Form#

1
import { Button } from "@/components/ui/button";
2
import { Textarea } from "@/components/ui/textarea";
3
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
4

5
interface VideoFormProps {
6
  onSubmit: (urls: string[], mode: string) => void;
7
  isLoading: boolean;
8
}
9

10
function VideoForm({ onSubmit, isLoading }: VideoFormProps) {
11
  const [urls, setUrls] = useState("");
12
  const [mode, setMode] = useState<"summary" | "detailed">("summary");
13

14
  function handleSubmit(e: React.FormEvent) {
15
    e.preventDefault();
16

17
    const urlList = urls
18
      .split("\n")
19
      .map((u) => u.trim())
20
      .filter((u) => u.length > 0);
21

22
    onSubmit(urlList, mode);
23
  }
24

25
  return (
26
    <Card>
27
      <CardHeader>
28
        <CardTitle>Process YouTube Videos</CardTitle>
29
      </CardHeader>
30
      <CardContent>
31
        <form onSubmit={handleSubmit} className="space-y-4">
32
          <Textarea
33
            placeholder="Paste YouTube URLs (one per line)"
34
            value={urls}
35
            onChange={(e) => setUrls(e.target.value)}
36
            className="min-h-[120px]"
37
          />
38

39
          <div className="flex gap-2">
40
            <Button
41
              type="button"
42
              variant={mode === "summary" ? "default" : "outline"}
43
              onClick={() => setMode("summary")}
44
            >
45
              Summary
46
            </Button>
47
            <Button
48
              type="button"
49
              variant={mode === "detailed" ? "default" : "outline"}
50
              onClick={() => setMode("detailed")}
51
            >
52
              Detailed
53
            </Button>
54
          </div>
55

56
          <Button type="submit" disabled={isLoading} className="w-full">
57
            {isLoading ? "Processing..." : "Process Videos"}
58
          </Button>
59
        </form>
60
      </CardContent>
61
    </Card>
62
  );
63
}

Part 4: Lessons Learned#

What Worked Well#

Pydantic models everywhere - Define once, validate everywhere. The auto-generated docs are a bonus.
React Query for polling - The refetchInterval option makes polling trivial. Stop polling when complete, no manual cleanup.
shadcn/ui components - Copy-paste beats npm dependencies. You can actually read and modify the code.
Dark mode first - Easier to start dark and add light than the reverse.
Two-panel layout - List on left, detail on right. Users understand it immediately.

What We’d Change#

Redis for job storage - Our in-memory store works for development, but won’t survive server restarts. Redis would be production-ready.
WebSocket for progress - We poll every 5 seconds, but WebSocket would give instant updates. Worth adding for better UX.
Better error boundaries - We handle API errors, but React error boundaries would catch rendering crashes.
E2E tests - Unit tests are great, but Playwright tests would catch integration issues.

Performance Tips#

Parallel video processing - We process 3 videos concurrently instead of sequentially. 3x speedup.
Reduced polling - Poll every 5 seconds, not 2. 60% fewer API calls.
Deduplicate URLs - Frontend removes duplicate video IDs before submission.
Incremental indexing - Only re-index notes when content changes.

The Full Stack in Action#

Here’s how a request flows through the system:

User enters YouTube URLs in the React form
Frontend sends POST to /api/youtube/process
FastAPI validates the request (Pydantic)
Backend creates a job, returns job ID
Frontend starts polling /api/youtube/status/{job_id}
Backend processes videos (Anthropic API)
Backend indexes notes (Qdrant)
Backend updates job status
Frontend sees “completed”, fetches results
User reviews and saves notes

Figure 4 - Request flow diagram showing the complete journey from user input through frontend, API, backend processing, and back to UI display

Key Takeaways#

FastAPI + Pydantic is the modern Python web stack. Type hints, validation, and docs for free.
React Query eliminates 90% of server state boilerplate. Use it.
shadcn/ui gives you polished components without dependency hell.
Dark mode first is easier than retrofitting.
Poll responsibly - 5 seconds is usually fine. Don’t hammer your own API.
Two-panel layout works for productivity apps. Don’t overthink it.

From YouTube to Knowledge Graph - System overview
Anthropic Batch API in Production - Backend processing
Building a Semantic Note Network - Vector search integration

This article is part of our series on building AI-powered knowledge management tools. Written with assistance from Claude Code.

The Architecture#

Part 1: FastAPI Backend#

Why FastAPI?#

Project Structure#

The Main App#

Request/Response Models#

Endpoint Patterns#

Background Jobs#

Part 2: React Frontend#

Why React + Vite?#

Project Structure#

The API Client#

React Query for Server State#

Part 3: Tailwind + shadcn/ui#

Why Tailwind?#

Why shadcn/ui?#

Dark Mode by Default#

Two-Panel Layout#

Component Example: Video Form#

Part 4: Lessons Learned#

What Worked Well#

What We’d Change#

Performance Tips#

The Full Stack in Action#

Key Takeaways#

Related Articles#