Dataset UI Interfaces
Relevant source files
The following files were used as context for generating this wiki page:
- apps/web/src/app/datasets/_components/dataset-grid.tsx
- apps/web/src/app/datasets/_components/dataset-search-bar.tsx
- apps/web/src/app/datasets/_components/dataset-filters.tsx
- apps/web/src/app/datasets/_components/dataset-card.tsx
- apps/web/src/app/datasets/upload/page.tsx
- apps/server/src/routes/v1/datasets.ts
The Dataset UI Interfaces in Poneglyph provide a comprehensive system for discovering, filtering, and contributing humanitarian data. These interfaces are primarily built using Next.js "use client" components, leveraging a centralized API for data fetching and state management through URL search parameters. Sources: apps/web/src/app/datasets/_components/dataset-grid.tsx, apps/web/src/app/datasets/upload/page.tsx
The system is designed around a modular architecture where the search bar, filter sidebar, and dataset grid interact via the browser's URL. This allows for shareable search states and a responsive user experience. Sources: apps/web/src/app/datasets/_components/dataset-search-bar.tsx:28-40, apps/web/src/app/datasets/_components/dataset-filters.tsx:43-51
Discovery and Navigation
The discovery interface is composed of three primary functional blocks: search, filtering, and the paginated results grid.
Search and Filtering Logic
The search functionality utilizes a debounced input that updates the q parameter in the URL. Filtering is handled by the DatasetFilters component, which manages status, file types, and language selections. Sources: apps/web/src/app/datasets/_components/dataset-search-bar.tsx:42-55, apps/web/src/app/datasets/_components/dataset-filters.tsx:83-157
The diagram above illustrates the unidirectional data flow where user interactions update the URL state, which subsequently triggers a re-fetch in the grid component. Sources: apps/web/src/app/datasets/_components/dataset-grid.tsx:32-35, apps/web/src/app/datasets/_components/dataset-search-bar.tsx:49-54
Dataset Presentation
Individual datasets are presented as DatasetCard components. These cards display metadata including the publisher, creation date, description, and available file types. Sources: apps/web/src/app/datasets/_components/dataset-card.tsx:16-95
| Feature | Component | Description |
|---|---|---|
| Search | DatasetSearchBar | Full-text search with 400ms debounce. |
| Filters | DatasetFilters | Radio and select inputs for Status, File Type, and Language. |
| Sorting | DatasetFilters | Options for Newest, Oldest, Most Viewed, and Most Downloaded. |
| Pagination | DatasetGrid | Previous/Next controls based on totalPages from API. |
Sources: apps/web/src/app/datasets/_components/dataset-filters.tsx:7-27, apps/web/src/app/datasets/_components/dataset-grid.tsx:68-111
Dataset Upload and Contribution
The upload interface allows users to contribute new datasets through a multi-step form that includes a real-time preview card. Sources: apps/web/src/app/datasets/upload/page.tsx:136-391
Upload Workflow
- Metadata Entry: Users provide a title, description, summary, and publisher information.
- File Selection: Supports drag-and-drop or file browsing for
.csv,.json,.jsonl, and.parquetformats. - Preview: A
DatasetPreviewCardupdates dynamically as the user fills out the form. - Submission: A multipart POST request is triggered to the server.
The sequence diagram shows the interaction between the form state, the live preview, and the eventual backend communication. Sources: apps/web/src/app/datasets/upload/page.tsx:166-173, apps/web/src/app/datasets/upload/page.tsx:356-365
API Integration and Data Model
The UI components communicate with the backend via the apiClient. The primary endpoint for the dataset list supports several query parameters that correspond directly to the UI filters. Sources: apps/web/src/app/datasets/_components/dataset-grid.tsx:21-35, apps/server/src/routes/v1/datasets.ts:54-73
Dataset List Parameters
| Parameter | Type | Description |
|---|---|---|
q | string | Search query for PostgreSQL full-text search. |
status | enum | Filter by pending, approved, rejected, or archived. |
fileType | enum | Filter by extensions like csv, pdf, json. |
sortBy | string | Field to sort by (e.g., viewCount, createdAt). |
sortOrder | string | asc or desc. |
Sources: apps/server/src/routes/v1/datasets.ts:54-68, apps/web/src/app/datasets/_components/dataset-filters.tsx:7-34
Implementation Detail: Pagination
The DatasetGrid component calculates the base URL for pagination links by preserving all current filter parameters and updating only the page index. Sources: apps/web/src/app/datasets/_components/dataset-grid.tsx:68-83
// apps/web/src/app/datasets/_components/dataset-grid.tsx:69-82
const createPageUrl = (newPage: number) => {
const params = new URLSearchParams();
if (props.q) params.set("q", props.q);
if (props.status) params.set("status", props.status);
if (props.fileType) params.set("fileType", props.fileType);
if (props.language) params.set("language", props.language);
if (props.sortBy) params.set("sortBy", props.sortBy);
if (props.sortOrder) params.set("sortOrder", props.sortOrder);
if (props.tags) {
props.tags.forEach((tag) => params.append("tags", tag));
}
params.set("page", newPage.toString());
return `/datasets?${params.toString()}`;
};
Summary
The Dataset UI Interfaces provide a robust framework for managing humanitarian intelligence assets. By utilizing a URL-driven state model, the system ensures that complex search and filter configurations remain persistent and easily shareable across the platform. The inclusion of a real-time upload preview ensures high-quality data contributions from researchers and NGOs. Sources: apps/web/src/app/datasets/_components/dataset-grid.tsx, apps/web/src/app/datasets/upload/page.tsx