# Chainkit

Chainkit is an SEO-friendly directory for discovering and sharing public, open-source AI tools used in supply chain planning, procurement, logistics, warehousing, and visibility. Tool detail pages are rendered on the server and included in the generated sitemap.

## Features

- Search and filter the directory by supply-chain category.
- Sort tools by rating, review count, and recency.
- Submit a project using its public GitHub repository URL.
- Rate tools from one to five stars; a browser can update its own rating.
- Per-tool metadata, canonical URLs, Open Graph tags, `robots.txt`, and `sitemap.xml`.
- BigQuery persistence on Google Cloud, with an in-memory sample directory for local development.
- Container deployment to Cloud Run.

The local demo directory uses real public GitHub repository links as examples; they are marked as starter data and have no pre-filled community ratings.

## Run locally

Requirements: Node.js 22+ and npm.

```sh
npm ci
copy .env.example .env.local
npm run dev
```

Open [http://localhost:3000](http://localhost:3000). Without BigQuery settings the app starts in local demo mode. Local submissions and ratings are held in server memory and reset when the server restarts.

## BigQuery

1. Create a BigQuery dataset in the region you plan to use.
2. Replace `YOUR_PROJECT_ID` and `YOUR_DATASET` in `infra/bigquery_schema.sql`, then run the SQL in the BigQuery console.
3. Configure Application Default Credentials locally, or attach a runtime service account to Cloud Run.
4. Set `BIGQUERY_PROJECT_ID`, `BIGQUERY_DATASET`, and `NEXT_PUBLIC_SITE_URL`.

The runtime service account needs `roles/bigquery.jobUser` on the project and `roles/bigquery.dataEditor` on the dataset. The app uses parameterized values for BigQuery writes; project and dataset identifiers are validated before being inserted into query text.

## Deploy to Cloud Run

Build and deploy the container from the repository root. Supply your canonical
domain if you already have one; otherwise omit `NEXT_PUBLIC_SITE_URL` on the
first deployment:

```sh
gcloud run deploy chainkit \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --service-account chainkit-runtime@YOUR_PROJECT_ID.iam.gserviceaccount.com \
  --set-env-vars BIGQUERY_PROJECT_ID=YOUR_PROJECT_ID,BIGQUERY_DATASET=YOUR_DATASET
```

After deployment, set `NEXT_PUBLIC_SITE_URL` to the Cloud Run URL or your
canonical domain so canonical links and the sitemap match the live site:

```sh
gcloud run services describe chainkit --region us-central1 --format="value(status.url)"
gcloud run services update chainkit \
  --region us-central1 \
  --update-env-vars NEXT_PUBLIC_SITE_URL=https://YOUR_CANONICAL_DOMAIN
```

The deployer needs permission to build/deploy the service and to act as the
runtime service account.

## Important production considerations

- Submissions are immediately public in this starter. Add moderation or an approval workflow before opening submissions to an untrusted audience.
- Ratings use a random browser-local identifier, not an authenticated user identity. It supports repeat edits from the same browser but is not abuse-resistant; add sign-in and rate limiting before treating ratings as verified.
- The repository URL is validated and stored as a link. Chainkit does not clone, fetch, or execute submitted code.
- BigQuery is optimized for analytics rather than high-volume transactional writes. For substantial rating or submission traffic, consider a transactional store and retain BigQuery for analytics.

## Project structure

```text
src/app/            Next.js pages, SEO routes, and API endpoints
src/lib/tools.ts    BigQuery adapter and local demo data
infra/              BigQuery table schema
Dockerfile           Cloud Run container
```