Now Builder Showcase is Becoming

GitHub repo → reviewed proof layer → recruiter/program-facing project page

The AI layer becomes the translation and improvement engine between raw project work and

publishable proof.

Where the AI Layer Fits

This is the placement in the system:

Submission created → README fetched → README safety checked → AI project review → private preview/staging page → admin/user revisions → approved → published showcase page

Which provides this workflow:

Raw repo + form metadata → AI-assisted project profile → reviewer/admin validation → publishable proof-of-work page

Why form metadata matters

The project README may be incomplete, so we will use the required form fields:

project title project category short description tags/tools repo URL README URL live demo URL ownership permission public showcase preference

This mitigates possible gaps like:

README does not clearly explain the project goal README does not mention the tools listed in the form README lacks setup/run instructions README lacks screenshots or demo explanation README does not explain the business/user problem README does not show outcomes, metrics, or results README title differs from submitted project title README category does not match project description

AI Layer v1 Concept

AI Project Readiness Review

readiness score summary quality score technical clarity score README completeness score recruiter-readiness score missing sections suggested improved project summary suggested tags/tools suggested resume bullet suggested showcase description risk flags publication recommendation

This becomes a real product feature.

New Database Idea

Possible table:

builder_ai_project_reviews

Possible fields

id
submission_id
builder_project_id
review_status
model_name
readme_snapshot
form_metadata_snapshot
ai_summary
ai_suggestions
missing_sections
readiness_score
recruiter_readiness_score
technical_clarity_score
publication_recommendation
created_at
updated_at
metadata

For simplicity at first:

With columns on builder_project_submissions:

ai_review_status
ai_reviewed_at
ai_review_summary
ai_review_metadata

Rationale:

For v1, we use a separate table because the review could be regenerated multiple times.

Private preview / staging idea

Project preview idea:

I do not need a full heavy staging site at first. I can start with a generated local/private

preview page or dashboard preview view:

Admin-only Streamlit preview

That is easier than deploying a separate staging site immediately.

Flow:

AI reads README + form metadata
→ AI generates suggested showcase page content
→ Streamlit shows private preview
→ admin accepts/edits/rejects suggestions
→ final content gets exported to YAML/page

Later, a true staging site can come in:

staging.datainsidedata.com

or:

GitHub Pages preview branch

AI Layer Should not Directly Publish

Integral: keep human approval in the loop.

The AI can suggest:

better title
better description
missing README sections
project summary
skills demonstrated
recruiter-facing explanation

But admin/user should approve before publishing.

That protects credibility!

This is fundable positioning:

This feature makes the product much easier to pitch because I am no longer just saying

We collect and display projects.

I’m saying:

We help transform raw GitHub repositories into reviewed, recruiter-ready proof-of-work profiles.

Solving the Ping

For workforce programs, bootcamps, nonprofits, and student cohorts, this solves a real pain:

Students build projects, but recruiters cannot quickly understand them.
Programs need proof of outcomes.
READMEs are inconsistent.
Project quality is hard to review at scale.

This is the bridge between Github and Recruiters!

Revised roadmap order

Finish the three draw.io diagrams
Document current architecture
Add AI layer design diagram
Add AI review database/schema plan
Build first local AI review script
Add AI review report function
Add AI Review tab to Streamlit dashboard
Add private preview page/view
Later: staging site or preview deployment

First AI Layer MVP

The first version should be small:

scripts/review_submission_with_ai.py

Input:

submission_id

It fetches:

submission form data
normalized README text
README check metadata

It outputs:

AI review JSON

suggestions
readiness scores
recommended showcase summary
missing sections

Then stores it in:

builder_ai_project_reviews

Then logs event:

ai_review_generated

This event fits the existing event model beautifully.

New event type

Add:

ai_review_generated

And later:

i_preview_generated
ai_suggestions_applied
ai_suggestions_rejected

Product Thesis Upgraded

This becomes:

A proof layer between GitHub and recruiters, powered by structured review, publishing workflows, analytics, and AI-assisted project readiness feedback. This feature makes the platform feel like a real product.

Rubric Scoring model

It is based on three things:

README/documentation best practices
recruiter/program proof-of-work requirements/needs
Builder Showcase publishing requirements

GitHub describes a README as a way to tell people why a project is useful, what they can do with it, and how to use it.
GitHub also recommends a README for every repository to make work easier to understand and navigate.
The Good Docs Project also treats README structure as customizable but section-based, which fits my idea of scoring sections rather than forcing every project into one rigid template.

AI Rubric a 100-point Project Readiness Score

Project Identity & Positioning — 15 pts
Problem / Purpose Clarity — 10 pts
Technical Stack & Architecture — 15 pts
Setup / Reproducibility — 15 pts
Usage / Demo Evidence — 10 pts
Results / Outputs / Impact — 10 pts
Documentation Quality — 10 pts
Recruiter Proof-of-Work Value — 10 pts
Safety / Publishing Readiness — 5 pts
Total: 100 pts

Rubric detail:

Project Identity & Positioning — 15 pts

Checks whether the project has:

clear title
short summary
category alignment
audience/user context
repo/form metadata consistency

This matters because a recruiter or reviewer should understand what the project is within seconds.

2. Problem / Purpose Clarity — 10 pts

Checks whether the README explains:

what problem the project solves
why it matters
who it helps
what motivated the build

This is where the “proof layer” becomes more than a repo link lol.

3. Technical Stack & Architecture — 15 pts

Checks whether the README explains:

languages
libraries/frameworks
database/backend/frontend tools
APIs/cloud services
system architecture
data flow
technical decisions

This is critical for showing technical depth.

4. Setup / Reproducibility — 15 pts

Checks whether someone can run or inspect the project:

installation steps
environment variables
requirements file
how to run locally
sample commands
known dependencies
notebook/script order

Installation and setup sections matter because README files are widely used to help users get started with GitHub projects. Research on README installation instructions found these sections are important but often suffer from documentation issues.

3 5. Usage / Demo Evidence — 10 pts

Checks for:

screenshots
demo link
sample input/output
walkthrough
dashboard image
video link
example workflow

This helps users quickly verify that the project is real and functional.

7. Documentation Quality — 10 pts

Checks for:

clear headings
logical structure
readable paragraphs
tables/lists where useful
not too thin
not too overwhelming
consistent formatting

A README can be technically complete but still hard to read. This category captures that.

9. Safety / Publishing Readiness — 5 pts

Checks for:

unsafe embedded HTML markers
iframe/script/form usage
broken or suspicious links
missing README URL
unclear ownership/permission
private or inaccessible assets

This connects to your existing README checker and publishing workflow.

Score bands

We’ll use these bands:

90–100: Showcase-ready
80–89: Strong, minor improvements
70–79: Publishable with revisions
60–69: Needs improvement before publication
Below 60: Not ready for showcase

AI output structure

The AI should return structured JSON, not just prose.

Something like:

{
  "overall_score": 82,
  "readiness_band": "Strong, minor improvements",
  "category_scores": {
    "project_identity": 13,
    "problem_purpose": 8,
    "technical_stack_architecture": 11,
    "setup_reproducibility": 10,
    "usage_demo": 7,
    "results_impact": 8,
    "documentation_quality": 8,
    "recruiter_proof_value": 9,
    "safety_publishing": 8
  },
  "top_strengths": [
    "Clear project title and category",
    "Strong workflow explanation",
    "Good evidence of dashboard functionality"
  ],
  "highest_priority_fixes": [
    "Add local setup instructions",
    "Add screenshots or demo walkthrough",
    "Clarify measurable outcomes"
  ],
  "suggested_showcase_summary": "...",
  "suggested_resume_bullet": "...",
  "publication_recommendation": "publish_with_minor_revisions"
}

What we should research next

I’ll do a focused market/best-practices scan around:

README structure standards
technical portfolio review criteria
bootcamp/career-services project evaluation rubrics
recruiter-facing project portfolio expectations
GitHub repo documentation best practices
AI-assisted documentation quality scoring

Then we can map that research into the rubric above and decide what belongs in v1 versus v2.

Recommendation

For v1, keep the rubric simple and explainable. A program manager, student, or funder should understand why a project scored 74 or 91.

The AI layer should not feel like a mysterious judge. It should feel like:

Here is what your project proves.
Here is what is missing.
Here is how to make it recruiter-ready.

That is the real product value.

Based on Research

My planned AI layer is aligned with a real market need. The big finding is this:

README quality is not just documentation quality. For Builder Showcase, it is proof-of-work quality.
A good scoring system should evaluate whether the project is understandable, reproducible, technically credible, recruiter-readable, and safe to publish.

README structure standards

The strongest baseline comes from GitHub itself: a README should explain why the project is useful, what people can do with it, and how they can use it. That maps almost perfectly to your planned rubric categories: purpose, functionality, setup, usage, and value.
The Good Docs Project adds useful tone and writing guidance: READMEs should be approachable, succinct, active-voice, and focused on why users would want to interact with the project, not only what the project does. That supports scoring for readability, positioning, and user/reviewer clarity.
CodeRefinery frames the README as usually the first thing users or collaborators see when visiting a repository, and says it should communicate important project information. That supports your “proof layer” concept because the README is often the first evidence artifact reviewers encounter.

Product implication:

Builder Showcase should score README structure, but not as a generic checklist. It should score whether the README helps a recruiter, reviewer, instructor, or program manager quickly understand the project.

Technical portfolio review criteria

Portfolio guidance is consistent**: projects need context, evidence, results, and an explanation of process. Indeed says portfolios can help employers understand a person’s abilities, problem-solving approach, growth, style, communication, and technical skills.
LinkedIn’s portfolio guidance emphasizes showing real projects aligned to the target industry and demonstrating process, decision-making, collaboration, obstacles, and practical evidence of thinking.

The recruiter-facing insight is that “raw work” is not enough. A project needs to explain:

what was built
why it matters
how it was built
what decisions were made
what evidence proves it works
what skills it demonstrates

Product implication:

The AI layer should not only ask, “Is this README complete?” It should ask, “Does this project prove something meaningful to a reviewer?”

Bootcamp / career-services rubric signals

Bootcamp and capstone sources are very aligned with my product. One Flatiron/Learn.co data science capstone rubric explicitly says most rubric objectives focus on the README and calls the README the “home page” of the capstone project. That is huge validation for my approach!
Tech Elevator describes capstones as preparation for real-world development and experience working with other developers. That supports scoring for team/process evidence, full-stack/system workflow, and real-world readiness.
NACE defines career readiness as the foundation for demonstrating workplace competencies, and its competency framework includes communication, critical thinking, professionalism, teamwork, technology, leadership, and career/self-development. That gives Builder Showcase a broader employability lens beyond just code quality.

Product implication:

The rubric should include a “career/recruiter proof value” category. This is where Builder Showcase becomes more than a README linter.

GitHub repository documentation best practices

The research literature supports what we are building. A 2018 README classification study found that README files shape first impressions of software repositories and that many READMEs lack purpose and status information; the study also found that automated section labeling helped software professionals discover information more easily.
A more recent README classification paper argues that README comprehensiveness influences repository adoption and utilization, and it demonstrates that LLM-based methods can classify README sections effectively.
Another paper notes that README and CONTRIBUTING files can serve as first points of contact for potential contributors, although many projects publish minimal READMEs rather than fuller community or process-oriented documentation.

Product implication:

Builder Showcase can score missing “purpose,” “status,” “setup,” “usage,” “results,” and “contribution/process” sections because these are recurring gaps in real repositories.

Recruiter-facing project portfolio expectations

The recruiter-facing market signal is clear: a project needs to show more than code. It should show context, problem-solving, results, and role relevance. Indeed emphasizes that a portfolio can provide context beyond a resume and show results through visual or written examples.
Portfolio hiring guidance also emphasizes selectivity, context, and showing process rather than just listing outputs.

This matters because GitHub alone often fails to communicate the career value of a project. That is the exact gap Builder Showcase can fill.

Product implication:

The AI layer should generate recruiter-facing suggestions such as:

project summary
skills demonstrated
resume bullet
portfolio description
missing proof points
reviewer-facing explanation

6. AI-assisted documentation quality scoring

The AI-assisted scoring direction is well supported, but the best practice should be human-in-the-loop, not fully automated judgment.

A 2026 README linting paper argues that what makes a good README varies by audience and context. It explores context-specific checks using both programmatic operations and LLM-based content evaluation while preserving authorial agency. That is almost exactly the design philosophy Builder Showcase should follow
A README simplification study found that software README files can be hard to understand due to jargon and complex sentence structure, and that transfer learning can help simplify README content while preserving meaning. That supports a future feature where Builder Showcase can suggest clearer recruiter-facing rewrites.

Product implication:

The AI should provide explainable suggestions, not just a score. The user should see what is missing, why it matters, and how to improve it.

Recommended Builder Showcase AI rubric v1

Market-aligned version:

Category	Points	Why it matters
Project Identity & Positioning	15	Can a reviewer quickly understand what this is?
Problem / Purpose Clarity	10	Does the project explain why it exists and who it helps?
Technical Stack & Architecture	15	Does it show real technical substance and decisions?
Setup / Reproducibility	15	Can someone run, inspect, or verify the work?
Usage / Demo Evidence	10	Is there proof the project works?
Results / Outputs / Impact	10	Does the project show outcomes, metrics, findings, or value?
Documentation Quality	10	Is the README readable, structured, and clear?
Recruiter Proof-of-Work Value	10	Does it translate work into employability evidence?
Safety / Publishing Readiness	5	Is it safe and appropriate to render/publish?

Total: 100 points

Score bands

90–100  Showcase-ready
80–89   Strong, minor improvements
70–79   Publishable with revisions
60–69   Needs improvement before publication
<60     Not ready for showcase

Proposed AI output

The AI review should return structured JSON like:

{
  "overall_score": 82,
  "readiness_band": "Strong, minor improvements",
  "publication_recommendation": "publish_with_minor_revisions",
  "category_scores": {
    "project_identity": 13,
    "problem_purpose": 8,
    "technical_stack_architecture": 12,
    "setup_reproducibility": 10,
    "usage_demo": 7,
    "results_impact": 8,
    "documentation_quality": 8,
    "recruiter_proof_value": 9,
    "safety_publishing": 7
  },
  "top_strengths": [],
  "highest_priority_fixes": [],
  "suggested_showcase_summary": "",
  "suggested_resume_bullet": "",
  "suggested_readme_sections": []
}

The market scan supports the product direction

The differentiator should not be “AI reads your README.” That is too generic.

The differentiator should be:

Builder Showcase turns raw GitHub projects into reviewed, recruiter-ready proof-of-work profiles using structured intake, README analysis, AI suggestions, publishing workflow, and operational dashboarding.

That is much stronger. It combines documentation quality, career readiness, program outcomes, and publishing operations into one system.

Then the AI Layer

Phase 5A — AI Project Readiness Review

That will include:

README + form metadata intake
README quality/rubric scoring
AI suggestions
recruiter-facing summary suggestions
missing section detection
private preview/staging concept
ai_review_generated event
AI Review dashboard tab

Product thesis I’m building toward

A proof-of-work platform that helps technical programs collect, review, improve, publish, and report on student and builder projects.

That is the SaaS path:

builder-showcase-data-flow.md
builder-showcase-publishing-pipeline.md
builder-showcase-security-rls-boundary.md

First Full AI Review Table

Slice 1: submission_id + review_status + raw README snapshot
Slice 2: form metadata snapshot + rubric version + scores
Slice 3: AI suggestions + recommended summary/resume bullet
Slice 4: private preview/staging fields
Slice 5: dashboard/reporting + ai_review_generated event

The table should allow multiple AI reviews per submission, because later I may regenerate a review after a user improves their README.

Step 1 — Create the AI review table

PgAdmin / Supabase SQL editor:

-- ============================================================
-- DataInsideData™ Builder Showcase
-- AI Project Review Layer
-- Table: builder_ai_project_reviews
-- ============================================================

Table Created, Now Scripts to interaction Proof with table

This lets us prove the AI review table is wired before adding model calls.

AI Review Layer Slice 1:

→ pull submission context
→ fetch normalized README Markdown
→ snapshot form metadata + README text
→ insert first AI review row
→ no AI call yet

First Script:

src/builder_showcase/ai_reviews.py

And:

sripts/create_ai_review_snapshot.py

Add AI review reporting functions so the dashboard can see this table.

src/builder_showcase/reports.py

README fetched ✅

README normalized ✅ README snapshot stored ✅ SHA256 created ✅ builder_project_id linked ✅ AI review table insert working ✅ active review versioning working ✅ review_status = queued ✅

AI Layer Runnable Scripts

python scripts/create_ai_review_snapshot.py --submission-id a3a7e274-ceca-4c8e-908b-08917faf2826

The AI layer is officially in the workflow now!

My event log confirms the new event is working:

ai_review_snapshot_created was logged with the review ID
review version 3, normalized README URL
SHA256 hash, README character count and stage = source_snapshot_only.

That means the AI review layer is now part of the same audit trail as

submission
README check
promotion
YAML export
and page generation.

Next slice: add AI review reporting functions so the dashboard can see this table

Terminal Testing:

python -c "from pathlib import Path; import sys; sys.path.insert(0, str(Path('src').resolve())); from builder_showcase.config import load_project_env; from builder_showcase.reports import get_ai_review_dashboard_kpis_df, get_ai_review_status_counts_df, get_active_ai_reviews_df; load_project_env(); print(get_ai_review_dashboard_kpis_df().to_string(index=False)); print(get_ai_review_status_counts_df().to_string(index=False)); print(get_active_ai_reviews_df().to_string(index=False))"

AI Review tab to Streamlit

This is after the above passing, which is now official

AI Review KPIs
AI Review Status Counts
Active AI Reviews
AI Review History by Submission

model scoring script:

scripts/generate_ai_project_review.py

Current State Is Excellent

AI review table ✅
README snapshot stored ✅
SHA256 tracking ✅
versioning/superseding ✅
event logging ✅
reports.py AI functions ✅
Streamlit AI Review tab ✅

Openai DID Proof Layer Project Key Strategy

This facilatates seperation of concerns:

Financial Intelligence Lab key → summaries/commentary
DID Proof Layer key → README/project readiness reviews

Did Proof Openai project:

did-proof-layer-local-dev openai project

Script:

python scripts/check_openai_proof_layer_key.py

How it Works

read active queued review

→ read form_metadata_snapshot
→ read readme_snapshot_md
→ send to OpenAI with rubric prompt
→ parse structured JSON
→ update builder_ai_project_reviews
→ set review_status = generated
→ log ai_review_generated

Run scrips

python scripts/generate_ai_project_review.py --submission-id a3a7e274-ceca-4c8e-908b-08917faf2826

Expected:

AI project review generated.
Overall score: ...
Readiness band: ...
Recommendation: ...

Updated AI review:

{'review_status': 'generated', ...}

Verify with:

python scripts/view_submission_events.py --submission-id a3a7e274-ceca-4c8e-908b-08917faf2826

should see:

ai_review_generated

Streamlit Application

streamlit run apps/builder_showcase_dashboard.py

The New AI Review Dashboard is Doing Exactly What I Wanted

Score-first view ✅
Recommendation-first view ✅
Readable project title + slug ✅
Review summary ✅
Rubric score breakdown ✅
Top strengths ✅
Priority fixes ✅
Suggested README sections ✅
Recruiter-facing summary ✅
Suggested resume bullet ✅
Compact table ✅

The biggest win is that it no longer feels like a real Proof Layer product feature.

The current split is beautiful for now:

AI Review Dashboard
→ human/product-facing review experience

AI Review — DB View
→ admin/debug/audit/database-style operational view

Also, the score and feedback make sense. A 53 with revise_before_publish is believable because the project is not fully polished yet, and the system caught concrete issues like unsafe iframe markers, weak usage/demo evidence, and missing architecture clarity. That means the rubric has teeth.

The UML and flow diagrams are going to help a lot because I now have several connected layers:

submission intake
README checking
AI source snapshot
AI scoring
event logging
dashboard reporting
publishing pipeline

Completed Phase 5A

AI review table

→ README snapshot
→ SHA256 tracking
→ AI scoring
→ reports.py
→ Streamlit AI Review Dashboard

Phase 5B — AI Review Actions / Admin Controls

Turn AI dashboard from read-only reporting into an admin action console.
Start with one clean AI Review Action Panel inside the AI Review Dashboard tab.

For v1, buttons should trigger the existing local/admin functions:

Create / Refresh Snapshot
Generate AI Review
Regenerate AI Review
Refresh Dashboard Data

Then later:

Accept AI Suggestions
Mark Needs Changes
Create Private Preview
Approve for Publishing

Button order:

Inside render_ai_review_dashboard_tab(data), after the project info mini-card and before Review Summary, add:

AI Review Actions
[Create New Snapshot] [Generate Review] [Regenerate Review] [Refresh Data]

The logic should be:

Create New Snapshot
→ calls create_ai_review_snapshot(submission_id)

Generate Review
→ calls generate_ai_project_review(ai_review_id or submission_id)

Regenerate Review
→ creates a new snapshot, then generates a fresh review

Refresh Data
→ clears Streamlit cache and reruns app
Important product rule

Buttons should be state-aware.

Example:

If review_status = queued:
    enable Generate Review

If review_status = generated:
    enable Regenerate Review

If no active review:
    enable Create Snapshot

Always allow Refresh Data, which prevents accidental bad workflow moves.

First simple implementation

At the top of apps/builder_showcase_dashboard.py, import:

from builder_showcase.ai_reviews import (
    create_ai_review_snapshot,
    generate_ai_project_review,
)

Empty Table Test

Since I removed all records tables

builder_project_submissions
builder_projects
builder_submission_events
builder_ai_project_reviews

and my current setup is

active_ai_reviews = empty

→ function returns early
→ row never exists
→ render_ai_action_panel(row) never runs
→ no buttons appear

The action panel is attached to an existing active AI review.

That works for:

queued review → Generate Review
generated review → Regenerate Review

But it does not help when starting from scratch because there is no active AI review yet.
No dashboard button can create an AI snapshot yet, because there is no submission_id to attach it to.

So I need two actions buttons:

1. Starter Actions
   For submissions that do not have AI reviews yet.
   Button: Create AI Snapshot

2. Review Actions
   For active AI review rows.
   Buttons: Generate Review, Regenerate Review, Refresh

The flow becomes:

Submit project through form

→ submission row exists
→ README check optional/recommended
→ Create AI Snapshot
→ Generate AI Review

The Real Validation Batch

Live/active projects test with new ai review button actions setup

projects with iframe/unsafe HTML + unfinished README
finished projects
existing live-site projects

Test whether the rubric can distinguish:

unsafe / unfinished
usable but incomplete
strong / recruiter-ready

Time to organize apps/builder_showcase_dashboard.py

Imports
Path setup / src import
Report/action imports
Page config
CSS styling
Data/value helpers
Chart helpers
Streamlit UI helpers
Cached data loading
Render sections / tabs
Main app

Organize helpers, etc., accordingly:

Data/value helpers
- to_streamlit_display_value
- safe_json_value
- humanize_label
- escape_text
- format_ai_score
- format_score
- format_hours
- metric_value_from_kpis
- make_streamlit_safe_df
- make_detail_table
- filter_submissions_df
- unique_options

Chart helpers
- format_chart_label
- render_bar_chart
- render_pivot_bar_chart
- build_rubric_scores_df
- render_rubric_score_chart

UI helpers
- show_df
- card
- section_title
- render_markdown_list

Cached data loading
- load_dashboard_data
- load_submission_drilldown

Render sections / tabs
- render_header
- render_kpi_cards
- render_ai_snapshot_starter_panel
- render_ai_action_panel
- render_overview_tab
- render_review_queue_tab
- render_readme_review_tab
- render_ai_review_dashboard_tab
- render_ai_review_db_view_tab
- render_published_tab
- render_activity_tab
- render_project_drilldown_tab

Main app
- main

If a render tab calls a helper, that helper should appear above it. render_ai_snapshot_starter_panel() and render_ai_action_panel() needs to come before render_ai_review_dashboard_tab()

After this test

Make sure to create buttons for project_submission promotions to builder_project table Make sure to create other buttons as needed.

Review Queue tab
→ human/admin status workflow

README Review tab
→ README safety/quality checking

AI Review Dashboard tab
→ AI snapshot + scoring + recommendation

Publishing / Project Drill-Down tab
→ promote + export + generated page actions

That keeps the system clean. The AI tab should not become the place that does everything.

The workflow should probably be submitted → reviewing → readme_checked → ai_reviewed → needs_changes OR approved → promoted_to_builder_project → exported_to_yml → detail_page_generated → published

The actual status column may not need every one of those as literal database statuses. Some of those can be inferred from events/tables. But conceptually, that is the pipeline

My honest recommendation:

Use separate action panels by job:

Review Queue tab
→ human/admin status workflow

README Review tab
→ README safety/quality checking

AI Review Dashboard tab
→ AI snapshot + scoring + recommendation

Publishing / Project Drill-Down tab
→ promote + export + generated page actions

That keeps the system clean. The AI tab should not become the place that does everything.

The workflow should probably be

submitted
→ reviewing
→ readme_checked
→ ai_reviewed
→ needs_changes OR approved
→ promoted_to_builder_project
→ exported_to_yml
→ detail_page_generated
→ published

Suggested Button/Action Layout

Review Queue tab

This is where the admin does the first human check.

Buttons/dropdowns:

Set Status: reviewing Set Status: needs_changes Set Status: approved

Optional later:

Open Repo Open README Open Live Demo

This tab answers:

Does the submitted project exist? Are the form fields valid? Is the repo accessible? Is this worth reviewing further?

README Review tab

This is where README safety happens.

Buttons:

Run README Check Recheck README

This updates:

readme_fetch_status readme_checked_at readme_check_notes readme_check_metadata

And logs:

readme_checked

Publishing controls

This should probably live in either:

Project Drill-Down

or a future:

Publishing Pipeline tab

Buttons:

Promote to Builder Project Export to YAML Generate Detail Page

Eventually one button can combine these:

Publish Approved Project

But I would not combine them too early. For testing, keeping them separate is better because I want to inspect each table and event after every step.

Your status logic idea is solid

The clean rule could be:

submitted → admin verifies repo/form fields → status = reviewing

reviewing → README check + AI review run

AI score < threshold or safety flagged → status = needs_changes

AI score >= threshold and admin agrees → status = approved

approved → promote to builder_projects → export YAML → generate page → status = published

For the threshold, I like:

90+ = showcase-ready 80–89 = strong, minor improvements 70–79 = publishable with revisions 60–69 = needs improvement below 60 = not ready

But I would not automatically publish only because score is 90+. The button should still require admin approval. AI is an advisor, not the final publisher.

So do you need 4 buttons instead of 2?

Yes — but I would frame it like this:

AI Review Dashboard buttons:

Create AI Snapshot
Generate AI Review
Regenerate AI Review
Mark Needs Changes

Then elsewhere:

Review Queue buttons/dropdown:

Set Reviewing
Set Needs Changes
Set Approved

And later:

Publishing buttons:

Promote to Builder Project
Export YAML / Generate Page
Publish Approved Project

Current Pipeline

Public form submission
→ Supabase Edge Function inserts builder_project_submissions
→ submission_created event logged
→ admin verifies submission / repo / form fields
→ update_submission_status()
→ README check via check_submission_readme.py / README checker functions
→ readme_checked event logged
→ AI snapshot via create_ai_review_snapshot()
→ AI score via generate_ai_project_review()
→ ai_review_generated event logged
→ status becomes needs_changes or approved
→ promote_submission_to_builder_project()
→ promoted_to_builder_project event logged
→ export_builder_projects()
→ exported_to_yml event logged
→ generate_builder_project_pages()
→ detail_page_generated event logged
→ submission status becomes published

Sources

GitHub Readme Docs: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes?utm_source=chatgpt.com
The Good Docs: https://www.thegooddocsproject.dev/template/readme?utm_source=chatgpt.com
CodeRefinery: https://coderefinery.github.io/documentation/writing-readme-files/?utm_source=chatgpt.com
Indeed: https://www.indeed.com/career-advice/resumes-cover-letters/build-your-work-portfolio?utm_source=chatgpt.com
Linkedin: https://www.linkedin.com/top-content/career/creating-an-online-portfolio/creating-a-portfolio-that-attracts-employers/?utm_source=chatgpt.com
GitHub Capstone: https://github.com/learn-co-curriculum/dsc-capstone-project-v2-3?utm_source=chatgpt.com
Tech Elevator: https://www.techelevator.com/bootcamp-curriculum-an-inside-look-at-tech-elevators-capstone-projects/?utm_source=chatgpt.com
NACE: https://www.naceweb.org/career-readiness/competencies/career-readiness-defined?utm_source=chatgpt.com
ArXiv: https://arxiv.org/abs/1802.06997?utm_source=chatgpt.com
ArXiv: https://arxiv.org/abs/2507.21899?utm_source=chatgpt.com
ArXiv: https://arxiv.org/abs/2502.18440?utm_source=chatgpt.com
Indeed: https://www.indeed.com/career-advice/resumes-cover-letters/build-your-work-portfolio?utm_source=chatgpt.com
We Love Salt: https://welovesalt.com/insights/what-hiring-managers-really-look-for-in-a-good-portfolio?utm_source=chatgpt.com
ArXiv: https://arxiv.org/abs/2603.00331?utm_source=chatgpt.com
ArXiv: https://arxiv.org/abs/2308.09940?utm_source=chatgpt.com