Diagram 1: System Architecture — draw.io-friendly layout

Diagram planning note:

TITLE: Builder Showcase System Architecture

LEFT SIDE — Public User Layer:

  • Builder / Student / Contributor
  • DataInsideData™ Submit Project Page
  • Browser Form Validation
  • Preview Submission Step
  • Confirm & Submit Step

CENTER — API / Security Layer:

  • Supabase Edge Function: submit-builder-project
  • CORS Handling
  • Public Form Key Check
  • JSON Payload Validation
  • Honeypot Check
  • Duplicate Submission Check
  • Client IP Hashing
  • Submission Insert
  • submission_created Event Log

CENTER-RIGHT — Database Layer:

  • builder_project_submissions
  • builder_submission_events
  • builder_projects

RIGHT SIDE — Admin Workflow Layer:

  • Python Admin Scripts
  • check_submission_readme.py
  • update_submission_status.py
  • promote_builder_project.py
  • export_builder_project.py
  • view_submission_events.py
  • view_builder_ops_summary.py

FAR RIGHT — Publishing / Dashboard Layer:

  • _data/builder_projects.yml
  • Generated Builder Showcase Detail Pages
  • Jekyll / Minimal Mistakes Site
  • Streamlit Builder Ops Dashboard
  • pgAdmin Business Queries

SECURITY BOUNDARY:

  • Public browser does not write directly to tables
  • Browser calls Edge Function
  • Edge Function uses server-side secret
  • Admin scripts use privileged local environment
  • RLS enabled on workflow tables
  • service_role has intentional grants

Diagram 2: Submission Lifecycle

TITLE: Builder Showcase Submission Lifecycle

FLOW:

  1. User opens Submit Builder Project page
  2. User enters project information
  3. Frontend validates fields
  4. User previews submission
  5. User confirms submission
  6. Edge Function receives POST request
  7. Edge Function validates request
  8. Edge Function checks honeypot and duplicates
  9. Edge Function inserts builder_project_submissions row
  10. Edge Function logs submission_created event
  11. Admin runs README checker
  12. README checker fetches normalized README URL
  13. README checker scans for unsafe markers
  14. README checker updates readme_fetch_status
  15. README checker logs readme_checked event
  16. Admin changes status to reviewing
  17. Status update logs status_changed event
  18. Admin promotes submission to builder_projects
  19. Promotion logs promoted_to_builder_project event
  20. Admin exports project to YAML
  21. Export logs exported_to_yml event
  22. Page generator creates/updates static project detail page
  23. Page generation logs detail_page_generated event
  24. Dashboard reports lifecycle and review health

Diagram 3: Event Logging Model

TITLE: Builder Showcase Event Logging Model

MAIN ENTITY: builder_submission_events

EVENT TYPES:

  • submission_created
  • readme_checked
  • status_changed
  • promoted_to_builder_project
  • exported_to_yml
  • detail_page_generated

EVENT SOURCES:

  • edge_function
  • local_admin

EVENT RELATIONSHIPS: builder_project_submissions.id → builder_submission_events.submission_id

builder_projects.id → builder_submission_events.builder_project_id

EVENT PURPOSE:

  • audit trail
  • lifecycle metrics
  • dashboard reporting
  • operational debugging
  • publishing history

##