> ## 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 (Symbols)

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

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

Reads `data/symbols_index.json` (cached in memory, 1 h TTL). Use these in Server Components
and route handlers — never in the browser.

```ts theme={null}
function searchSymbols(query: string, category?: string, page = 1, limit = 20): SearchResult;
function getSymbolById(id: string): Symbol | undefined;          // id = "Library:Name"
function getLibraryByName(name: string): LibraryDetail | undefined;
function getAllLibraries(category?: string): Library[];
function getStats(): { totalSymbols: number; totalLibraries: number; totalContributors: number };
function getCategoryStats(): { id: string; count: number }[];
```

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

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

```ts theme={null}
// catalog
searchSymbols(query, { category?, page?, limit? }): Promise<SearchResult>;
searchSymbolsSemantic(query, limit?): Promise<{ results, total, source } | null>;
fetchSymbolById(id): Promise<Symbol | null>;
fetchLibraries({ category?, page?, limit? }): Promise<{ libraries, total }>;
fetchLibrary(name): Promise<LibraryDetail | null>;
downloadLibrary(name): Promise<Blob>;
// generation / persistence (auth)
generateSymbol(description, { datasheet_url?, additional_instructions? }): Promise<{ data: GenerateSymbolResult; status }>;
saveGeneratedComponent(payload: SaveComponentPayload): Promise<SaveResult>;
// contribution (auth)
validateSymbol(file): Promise<ValidationResult>;
submitContribution(data: ContributionData): Promise<SubmissionResponse>;
// user
fetchUserProfile(): Promise<UserProfile | null>;
```

## Types

```ts theme={null}
interface SearchResult { symbols: Symbol[]; total: number; page: number; limit: number; totalPages: number; }
interface Library { id: string; name: string; description: string; category: string;
  symbolCount: number; lastUpdated: string; contributor: string; source?: string; }
interface LibraryDetail extends Library { symbols: Symbol[]; }
```

See [Generate](/platforms/symbols/generate) for `GenerateSymbolResult` and
[API Reference](/platforms/symbols/api-reference) for `SaveComponentPayload`. The `Symbol`
and `Pin` shapes are in [Overview](/platforms/symbols/overview).

<Info>
  Reads go through the static index, so the catalog API is fast and resilient. Only
  generation, save, contribution, and account calls touch the backend.
</Info>