Frontend API Layer

Project Structure

The frontend is built with React 19 and TypeScript, organized into feature-based folders:

src/
├── api/
│   └── photos-api.ts           # All network calls
├── features/
│   ├── photos/                 # Photo display components
│   └── upload/
│       ├── SimpleUploadForm.tsx
│       └── UploadForm.tsx
└── App.tsx                     # Routing

Keeping all API calls in one file means components never call fetch directly — they only deal with typed results.

The Result Pattern

Rather than throwing exceptions on failure, every API function returns an ApiResult<T> — a discriminated union that forces callers to handle both outcomes:

frontend/src/api/photos-api.ts#L12-L18 on GitHub

// src/api/photos-api.ts

export type ApiResult<T> = {
    success: true;
    data: T;
} | {
    success: false;
    error: string;
};

TypeScript narrows the type automatically when you check result.success:

const result = await uploadPhoto(formData);

if (result.success) {
    console.log(result.data); // TypeScript knows this is PhotoResponse
} else {
    console.log(result.error); // TypeScript knows this is string
}

Accessing result.data without checking result.success first is a type error — TypeScript enforces correct error handling at compile time.

Response Types

frontend/src/api/photos-api.ts#L4-L9 on GitHub

export type PhotoResponse = {
    id: number;
    photo_url: string;
    title?: string;
    description?: string;
};

This mirrors the PhotoResponse Pydantic model on the backend.

API Functions

frontend/src/api/photos-api.ts#L23-L86 on GitHub

const baseUrl = import.meta.env.VITE_API_URL ?? "http://localhost:8000";

export async function getAllPhotos(): Promise<ApiResult<PhotoResponse[]>> {
    try {
        const response = await fetch(`${baseUrl}/api/photos`);
        if (!response.ok) {
            return { success: false, error: "Couldn't fetch photos" };
        }
        const photos = await response.json();
        return { success: true, data: photos };
    } catch (e) {
        return {
            success: false,
            error: e instanceof Error ? e.message : "Unknown error occurred"
        };
    }
}

export async function uploadPhoto(formData: FormData): Promise<ApiResult<PhotoResponse>> {
    try {
        const response = await fetch(`${baseUrl}/api/photos`, {
            method: "POST",
            body: formData,
        });

        if (!response.ok) {
            return { success: false, error: "Unable to upload image" };
        }

        const photo = await response.json();
        return { success: true, data: photo };
    } catch (e) {
        return {
            success: false,
            error: e instanceof Error ? e.message : "Unknown error occurred"
        };
    }
}

Why this approach?

• No try/catch in components — error handling is centralised here, not scattered across the codebase
• Consistent error shape — every failure produces { success: false, error: string }, whether it’s a network error, a 400 from the server, or anything else
• Easy to test — functions return plain objects, no exception mocking required
• Type-safe at the call site — TypeScript won’t let you use result.data without first confirming result.success === true

Uploading with FormData

The uploadPhoto function passes FormData directly as the request body. The browser sets the correct Content-Type: multipart/form-data header automatically — you should not set it manually, as doing so omits the boundary string that the server needs to parse the body.