Community
Pipeline
Scans
Stack
Code Quality
AI
Support

DEV Community Dashboard

A signal-surfacing tool for Forem communities (dev.to and self-hosted instances). It ingests the latest posts via the public Forem API, classifies each one into attention categories (Awaiting Collaboration, Anomalous Signal, Trending Signal, Rapid Discussion, Steady Signal), and persists the results in Supabase so community helpers can see where conversations need a human eye.

This is not a moderation tool or a scorecard. It is designed to help helpers know where to look.

Production: https://dev-signal.checkmarkdevtools.dev (Cloud Run -- deployed post-initial-release)

v1.1.0 adds LLM interaction scoring, NEEDS_SUPPORT detection, and incremental caching and was created for the DEV Weekend Challenge.

---

Documentation

Document	Description
Architecture	System overview, data flow diagrams, deployment, API routes, guardrails
Interaction Signal	Composite signal formula, LLM scoring pipeline, model cascade, heuristic fallback, incremental scoring, signal spread, topic tags
Metrics Reference	Full ArticleMetrics field reference, risk components, velocity, participation, attention categories, chart mappings
Database Migrations	Migration history and schema notes
Project Conventions	AI rules, testing requirements, commit conventions, CI policies

---

Quick Start

Prerequisites

• Node.js >= 22 (matches Volta pin and CI/Docker toolchain)
• pnpm
• A Supabase project with RLS migrations applied

supabase db push
# or run supabase/migrations/0001_rls_policies.sql manually in the SQL editor

Environment Variables

Create a .env file in the project root:

Variable	Required	Description
NEXT_PUBLIC_SUPABASE_URL	Yes	Supabase project URL
SUPABASE_SECRET_KEY	Yes	Server-only key; bypasses RLS for sync writes
CRON_SECRET	Yes	Bearer token for /api/cron and /api/admin/seed
DEV_API_KEY	No	Raises Forem API rate limits
OPENAI_API_KEY	No	Enables LLM interaction scoring; absent = heuristic fallback

SUPABASE_SECRET_KEY is intentionally not prefixed with NEXT_PUBLIC_ -- it is never sent to the browser.

Commands

pnpm install          # install dependencies
pnpm dev              # development server -> http://localhost:3000
pnpm test             # run full Vitest test suite
pnpm build            # type-check + Next.js production build

---

API Reference

Method	Path	Auth	Description
GET	/api/posts	None	Top 50 articles (7-day window), non-NORMAL first, score desc, oldest first
GET	/api/posts/:id	None	Article detail + 5 most recent posts by same author
POST	/api/cron	Bearer	Purge articles > 10 days, then sync articles in the 5-day window from Forem
POST	/api/admin/seed	Bearer	Same as cron -- populate the database on first deploy

---

Deployment (Cloud Run)

Run ./deploy.sh from the repo root. The script handles Secret Manager secrets, Artifact Registry, Cloud Build, and Cloud Run deployment.

gcloud auth login
gcloud config set project checkmarkdevtools

Set APP_URL as a GitHub repository variable and CRON_SECRET as a GitHub secret so the cron workflow can reach the deployed endpoint.

---

GitHub Actions Workflows

All CI checks run in ci.yml; do not create additional workflow files for individual checks.

Workflow	File	Trigger	What It Does
CI	ci.yml	Push to main, Pull Request	Format, lint, Vitest + coverage, SonarCloud scan, Lighthouse CI
Hourly Sync	cron.yml	Schedule (0 * * * *), manual	POSTs to /api/cron; skips if APP_URL or CRON_SECRET is unset
Release Please	release-please.yml	Push to main	Automated release PRs (Conventional Commits -> CHANGELOG + version bump)

Required Repository Configuration

Name	Type	Used by	Notes
APP_URL	Variable	cron.yml	Public Cloud Run URL
CRON_SECRET	Secret	cron.yml	Must match the CRON_SECRET env var on the deployed service
SONAR_TOKEN	Secret	ci.yml	SonarCloud token
GITHUB_TOKEN	Built-in	ci.yml, release	release-please.yml needs contents: write, pull-requests: write

---

Contributing

This project is built for community helpers -- people who want to know where to look, not what to do. The dashboard surfaces conversations that may need a human eye; it does not assign blame, issue warnings, or score individuals.

Area	Where to Look
Scoring and classification logic	src/lib/sync.ts
LLM interaction analysis (OpenAI)	src/lib/openai.ts
Dashboard UI components	src/components/Dashboard.tsx, src/components/ui/
Chart components (custom SVG)	src/components/ui/charts/
Chart data transformation helpers	src/lib/metrics-helpers.ts
Display helpers (labels, narratives)	src/lib/dashboard-helpers.ts
API routes	src/app/api/
Tests	Co-located *.test.ts / *.test.tsx
CI checks	.github/workflows/ci.yml
Project conventions	AGENTS.md

---

AI and Guardrails

This project uses AI tooling to generate code -- and that is precisely why the guardrails are as strict as they are. AI writes plausible-looking code that is sometimes subtly wrong. The CI pipeline, Sonar analysis, test coverage requirements, and pre-commit hooks all exist to catch what AI misses.

AI use is encouraged here, not discouraged. But it is not a standalone solution. Use it with the safety net on.

---

Connect and Support

---

License

This project is licensed under the Polyform Shield License 1.0.0.

Copyright (c) 2026 ChecKMarK DevTools & Ashley Childress

In brief:

• You CAN use, copy, fork, or adapt this for your own workflows, inside your company, for client projects, demos, education, or anything else -- as long as you are not selling the code, charging for it, or making money from the project itself.
• You CANNOT resell, offer as a paid service, or monetize this project or its derivatives without prior written approval from Ashley Childress.
• Any public fork, copy, or substantial reuse must include the LICENSE file and a clear attribution statement in your documentation or README:

  "Based on original work by ChecKMarK DevTools & Ashley Childress -- see https://github.com/checkmarkdevtools/dev-community-dashboard."

For exceptions or monetization/commercialization questions, contact Ashley Childress at human@checkmarkdevtools.dev.

See the full LICENSE file for details.