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

> Discover how the CodeWiki Next.js frontend integrates with the FastAPI backend using REST APIs and Redis for real-time asynchronous wiki generation and progress updates.

- Repository: [Luong Quang Dung/codewiki](https://github.com/quangdungluong/codewiki)
- Tags: deep-dive
- Published: 2026-02-16

---

**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:

```typescript
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`](https://github.com/quangdungluong/codewiki/blob/main/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:

```python
@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:

```typescript
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`](https://github.com/quangdungluong/codewiki/blob/main/api/wiki.py) at line 65, retrieving the current state from Redis:

```python
@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:

```typescript
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`](https://github.com/quangdungluong/codewiki/blob/main/api/wiki_cache.py) at line 55, reading JSON cache files directly from disk:

```python
@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`](https://github.com/quangdungluong/codewiki/blob/main/frontend/components/ProcessedProjects.tsx) at line 61:

```typescript
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`](https://github.com/quangdungluong/codewiki/blob/main/api/processed_projects.py) at line 11 scans the cache directory to build the project list:

```python
@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`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/ProcessedProjects.tsx) and [`page.tsx`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/utils/redis_tasks.py). Once completed, wiki content persists as JSON files on the file system, served through the [`api/wiki_cache.py`](https://github.com/quangdungluong/codewiki/blob/main/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`](https://github.com/quangdungluong/codewiki/blob/main/page.tsx) and [`ProcessedProjects.tsx`](https://github.com/quangdungluong/codewiki/blob/main/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.