| # 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 |
| ``` |
|
|
