https://github.com/anchildress1/dev-community-dashboard
Community behavior analytics dashboard for DEV.to. Observes activity patterns, engagement dynamics, and moderation signals without judging individual users.
https://github.com/anchildress1/dev-community-dashboard
analytics community-analytics conversation-analysis dashboard devchallenge developer-community devto engagement-metrics weekend-challenge
Last synced: 5 days ago
JSON representation
Community behavior analytics dashboard for DEV.to. Observes activity patterns, engagement dynamics, and moderation signals without judging individual users.
- Host: GitHub
- URL: https://github.com/anchildress1/dev-community-dashboard
- Owner: anchildress1
- License: other
- Created: 2026-02-27T20:01:39.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-06-27T21:00:16.000Z (19 days ago)
- Last Synced: 2026-06-27T21:11:34.553Z (19 days ago)
- Topics: analytics, community-analytics, conversation-analysis, dashboard, devchallenge, developer-community, devto, engagement-metrics, weekend-challenge
- Language: TypeScript
- Homepage: https://dev-signal.checkmarkdevtools.dev
- Size: 7.39 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
Community
[](https://github.com/ChecKMarKDevTools/dev-community-dashboard/stargazers) [](./LICENSE) [](https://dev.to/anchildress1)
Pipeline
[](https://github.com/ChecKMarKDevTools/dev-community-dashboard/actions/workflows/ci.yml) [](https://github.com/ChecKMarKDevTools/dev-community-dashboard/actions/workflows/cron.yml) [](https://sonarcloud.io/summary/overall?id=ChecKMarKDevTools_forem-community-dashboard) [](https://sonarcloud.io/summary/overall?id=ChecKMarKDevTools_forem-community-dashboard)
Scans
[](https://trufflesecurity.com/trufflehog) [](https://semgrep.dev) [](https://github.com/ChecKMarKDevTools/dev-community-dashboard/security/code-scanning) [](https://github.com/hadolint/hadolint) [](https://github.com/rhysd/actionlint) [](https://stylelint.io) [](https://developer.chrome.com/docs/lighthouse)
Stack
[](https://nextjs.org) [](https://www.typescriptlang.org) [](https://tailwindcss.com) [](https://supabase.com) [](https://vitest.dev) [](https://pnpm.io) [](https://www.docker.com) [](https://cloud.google.com/run)
Code Quality
[](https://eslint.org) [](https://prettier.io) [](https://www.conventionalcommits.org) [](https://github.com/evilmartians/lefthook) [](https://www.gnu.org/software/make/)
AI
[](https://claude.ai) [](https://chat.openai.com) [](https://platform.openai.com/docs/models) [](https://deepmind.google/models/gemini/) [](https://leonardo.ai)
Support
[](https://github.com/sponsors/anchildress1) [](https://buymeacoffee.com/anchildress1)
# DEV Community Dashboard
A signal-surfacing tool for [Forem](https://forem.com/) communities (dev.to and self-hosted instances). It ingests the latest posts via the public Forem API, classifies each one into seven attention categories (Needs Support, Awaiting Collaboration, Anomalous Signal, Trending Signal, Rapid Discussion, Silent Signal, 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](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](https://dev.to/devteam/happening-now-dev-weekend-challenge-submissions-due-march-2-at-759am-utc-5fg8).
---
## Documentation
| Document | Description |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| **[Architecture](./docs/architecture.md)** | System overview, data flow diagrams, deployment, API routes, guardrails |
| **[Interaction Signal](./docs/interaction-signal.md)** | Composite signal formula, LLM scoring pipeline, model cascade, heuristic fallback, incremental scoring, signal spread, topic tags |
| **[Metrics Reference](./docs/metrics.md)** | Full `ArticleMetrics` field reference, risk components, velocity, participation, attention categories, chart mappings |
| **[Database Migrations](./supabase/README.md)** | Migration history and schema notes |
| **[Project Conventions](./AGENTS.md)** | AI rules, testing requirements, commit conventions, CI policies |
---
## Quick Start
### Prerequisites
- Node.js >= 22 (matches Volta pin and CI/Docker toolchain)
- pnpm
- A [Supabase](https://supabase.com/) project with RLS migrations applied
```bash
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
```bash
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.
```bash
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
[](https://dev.to/anchildress1) [](https://linkedin.com/in/anchildress1) [](https://medium.com/@anchildress1) [](https://reddit.com/user/anchildress1)
[](https://github.com/sponsors/anchildress1) [](https://buymeacoffee.com/anchildress1)
---
## License
This project is licensed under the **[Polyform Shield License 1.0.0](https://polyformproject.org/licenses/shield/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](https://github.com/checkmarkdevtools/dev-community-dashboard)."
For exceptions or monetization/commercialization questions, contact Ashley Childress at [human@checkmarkdevtools.dev](mailto:human@checkmarkdevtools.dev).
See the full [LICENSE](./LICENSE) file for details.