How the CodeWiki Frontend Integrates with the FastAPI Backend: A Complete Technical Guide

The CodeWiki Next.js frontend communicates with the FastAPI backend through REST endpoints under /api/, using Redis-backed background tasks for asynchronous wiki generation and polling mechanisms for real-time progress updates.

The quangdungluong/codewiki repository implements a clean client-server architecture where a React/TypeScript frontend orchestrates complex documentation generation workflows. Understanding how the CodeWiki frontend integrates with the FastAPI backend reveals sophisticated patterns of asynchronous job processing, state persistence, and efficient caching strategies that keep the UI responsive during long-running operations.

Architecture Overview

The integration follows a strict separation of concerns. The Next.js frontend in frontend/app/[owner]/[repo]/page.tsx remains agnostic of heavy-weight processing logic, while the FastAPI backend handles resource-intensive wiki generation through background tasks. All inter-process communication occurs via HTTP requests to endpoints mounted under the /api/ path, with Redis serving as the state management layer for asynchronous operations.

Core Integration Patterns

Initiating Wiki Generation via POST /api/wiki/generate

The workflow begins when users submit repository details through the frontend. In frontend/app/[owner]/[repo]/page.tsx at line 96, the frontend constructs a POST request to trigger generation:

const response = await fetch(`/api/wiki/generate`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    owner: effectiveRepoInfo.owner,
    repo: effectiveRepoInfo.repo,
    repo_info: { type: effectiveRepoInfo.type },
    repo_url: effectiveRepoInfo.repoUrl,
    token: '',
  }),
});

The backend receives this in api/wiki.py at line 12, where the generate_wiki endpoint creates a unique task ID, initializes state in Redis via RedisTasks().add_task(), and delegates processing to a FastAPI background task:

@router.post("/generate")
async def generate_wiki(wiki: WikiTaskRequest, background_tasks: BackgroundTasks):
    task_id = str(uuid.uuid4())
    RedisTasks().add_task(task_id, {"status": "started", "message": "Generating wiki...", "progress": [], "error": None, "result": None})
    background_tasks.add_task(generate_wiki, wiki, task_id)
    return {"task_id": task_id}

Real-Time Progress Polling via GET /api/wiki/status/{task_id}

Upon receiving the task ID, the frontend enters a polling loop to track execution progress. In frontend/app/[owner]/[repo]/page.tsx at line 206, a setInterval repeatedly queries the status endpoint every 2 seconds:

const pollStatus = async (id: string) => {
  const res = await fetch(`/api/wiki/status/${id}`);
  const data = await res.json();
  // update UI based on data.status, data.message, data.progress …
};
intervalRef.current = setInterval(() => pollStatus(taskId), 2000);

The backend handles these requests in api/wiki.py at line 65, retrieving the current state from Redis:

@router.get("/status/{task_id}", response_model=WikiTaskStatus)
async def get_task_status(task_id: str):
    task = RedisTasks().get_task(task_id)
    if task is None:
        raise HTTPException(status_code=404, detail="Task not found")
    return task

Retrieving Cached Results via GET /api/wiki_cache

For previously generated wikis, the frontend avoids redundant processing by checking the file-system cache. In frontend/app/[owner]/[repo]/page.tsx at line 86:

const checkCache = async () => {
  const response = await fetch(`/api/wiki_cache?owner=${owner}&repo=${repo}`);
  if (response.ok) {
    const data = await response.json();
    // Render cached wiki content
  }
};

The backend serves this from api/wiki_cache.py at line 55, reading JSON cache files directly from disk:

@router.get("")
async def get_wiki_cache(owner: str, repo: str):
    cache_data = read_wiki_cache_data(owner, repo)
    if cache_data is None:
        raise HTTPException(status_code=404, detail="Wiki not found in cache")
    return cache_data

Listing Processed Projects via GET /api/wiki/projects

The home page displays previously processed repositories by querying the processed projects endpoint. In frontend/components/ProcessedProjects.tsx at line 61:

const fetchProjects = async () => {
  const response = await fetch('/api/wiki/projects');
  if (!response.ok) throw new Error('Failed to fetch projects');
  return response.json();
};

The backend implementation in api/processed_projects.py at line 11 scans the cache directory to build the project list:

@router.get("")
async def get_processed_projects():
    projects = get_cached_projects()
    return {"projects": projects}

Data Flow and State Management

The integration relies on a three-tier persistence strategy that separates transient state from permanent storage:

• Redis for Task State: The RedisTasks utility in utils/redis_tasks.py maintains ephemeral state for active wiki generation jobs, enabling real-time progress updates without blocking HTTP connections.

• File System for Results: Completed wikis persist as JSON files on disk, served directly by api/wiki_cache.py for immediate retrieval without reprocessing.

• In-Memory Polling: The frontend maintains local state through React hooks while polling GET /api/wiki/status/{task_id} every 2 seconds until completion.

Error Handling Strategies

Both layers implement robust error handling that propagates meaningful status codes across the stack. The backend returns standard HTTP status codes—404 for missing tasks in api/wiki.py, and 500-level errors for processing failures. The frontend validates responses using the response.ok property, throwing JavaScript Errors that trigger UI error boundaries in components like ProcessedProjects.tsx and page.tsx.

Summary

• The CodeWiki frontend integrates with the FastAPI backend through REST endpoints mounted under /api/, using JSON for data exchange.
• Asynchronous processing uses FastAPI BackgroundTasks with Redis persistence via RedisTasks in utils/redis_tasks.py.
• Real-time progress tracking relies on frontend polling against GET /api/wiki/status/{task_id} every 2 seconds.
• Caching strategy combines Redis for active jobs and file-system storage for completed wikis, accessed via api/wiki_cache.py.
• Error handling spans both layers, with HTTP status codes from the backend and response.ok validation in the frontend.

Frequently Asked Questions

What technology stack does CodeWiki use for frontend-backend communication?

CodeWiki employs a modern stack where the Next.js frontend (React/TypeScript) communicates with a Python FastAPI backend via standard HTTP REST endpoints. The architecture uses Redis as an in-memory data store for managing asynchronous task state, while the file system stores completed wiki results as JSON files.

How does CodeWiki handle long-running wiki generation without blocking the UI?

The backend leverages FastAPI's BackgroundTasks to offload wiki generation processing, immediately returning a task_id to the frontend. The frontend then polls the GET /api/wiki/status/{task_id} endpoint every 2 seconds to retrieve real-time progress updates from Redis, keeping the UI responsive throughout the operation.

Where does CodeWiki store generated wiki data?

CodeWiki implements a two-tier storage strategy. Active generation tasks maintain their state in Redis via the RedisTasks utility in utils/redis_tasks.py. Once completed, wiki content persists as JSON files on the file system, served through the api/wiki_cache.py router for fast subsequent retrieval without reprocessing.

How does the frontend detect and display errors from the backend?

The frontend validates all API responses using the response.ok property, throwing JavaScript Errors when encountering HTTP 4xx or 5xx status codes. These errors propagate to React error boundaries in components like page.tsx and ProcessedProjects.tsx, which render user-friendly error messages while the backend returns specific HTTP status codes such as 404 for missing tasks or 500 for processing failures.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}