> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithtrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Layer (Footprints)

> The server-side index reader and the client API wrapper for the Trace Footprints platform.

## Server: `src/lib/footprints.ts`

Reads `data/footprints_index.json` (cached in memory, 1 h TTL). Use in Server Components and
route handlers.

```ts theme={null}
function searchFootprints(query: string, page = 1, limit = 20): FootprintSearchResult;
function getFootprintById(id: string): Footprint | undefined;
function getFootprintsByLibrary(libraryId: string, page = 1, limit = 60): FootprintSearchResult;
function getAllFootprintLibraries(): FootprintLibrary[];               // { id, name, footprintCount }
function getTopFootprintLibraries(limit = 12): FootprintLibrary[];     // sorted by count desc
function getFootprintStats(): { totalFootprints: number; totalLibraries: number };
```

## Client: `src/lib/api.ts`

Browser-safe wrappers over the site routes, plus auth helpers from `lib/auth.ts`.

```ts theme={null}
// catalog
searchFootprints(query, { page?, limit? }): Promise<FootprintSearchResult>;
fetchFootprintById(id): Promise<Footprint | null>;
// generation / persistence (auth)
generateFootprint(description, { package_type? }): Promise<{ data: GenerateFootprintResult; status }>;
saveGeneratedComponent(payload: SaveComponentPayload): Promise<SaveResult>;   // type: "footprint"
// contribution (auth)
validateFootprint(file): Promise<ValidationResult>;        // { valid, errors, warnings, footprintName, padCount }
submitContribution(data: ContributionData): Promise<SubmissionResponse>;
// user
fetchUserProfile(): Promise<UserProfile | null>;
```

## Types

```ts theme={null}
interface Footprint {
  id: string; name: string; library: string; description: string; tags: string;
  padCount: number; pads: Array<{ number: string; type: string }>;
  model3d?: string | null; source?: "trace" | "cern";
}
interface FootprintLibrary { id: string; name: string; footprintCount: number; }
interface FootprintSearchResult {
  footprints: Footprint[]; total: number; page: number; limit: number; totalPages: number;
}
interface GenerateFootprintResult {
  success: boolean; footprintName: string; description?: string;
  kicadMod: string | null; padCount: number; pads: Array<{ number: string; type: string }>;
  traceJson?: object; source?: string; note?: string; error?: string;
}
```

<Info>
  The footprints repo is footprint-only: `lib/types.ts` contains just the `Footprint*` types
  (no `Symbol`/`Pin`), and `lib/api.ts` contains only footprint + shared (auth/contribute/user)
  functions.
</Info>