This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
INESC TEC Open-Source Software showcase website - a React application displaying open-source projects organized by innovation areas (Energy, Robotics, AI, Industry).
Live site: https://inesctec.github.io/
npm start # Development server (localhost:3000)
npm run build # Production build
npm run deploy # Build and deploy to GitHub Pages
npm test # Run tests (interactive watch mode)
npm test -- --watchAll=false # Run tests once- Uses HashRouter (required for GitHub Pages compatibility)
- Routes defined in
src/App.jswith lazy loading viaReact.lazy()+Suspense - URL query params used for category filtering:
?category=Energy
- No global state management - each page manages its own state with
useState - Project and area data fetched from JSON files in
/public/directory:/public/projects_input.json- hand-edited source of truth for projects (never read by the app directly)/public/projects.json- GENERATED fromprojects_input.jsonbyscripts/update_projects.py; do not hand-edit, it is overwritten on every run/public/areas.json- innovation areas with featured projects; hand-edited, buttotal_stars/total_reposare rewritten in place byscripts/update_areas.py
- Client-side filtering, searching, sorting, and pagination
- Logos are loaded dynamically via
import(\../assets/${project_logo}`)inProjectCard.jsandAreaCard.js, soproject_logois a filename insidesrc/assets/`
.github/workflows/update-json-files.ymlruns daily (cron), on every push tomaster, and on manual dispatch. It runsupdate_areas.pythenupdate_projects.pyand commitsareas.json/projects.jsonasgithub-actions[bot]when they change..github/workflows/auto-deploy.yml(workflow_runon "Update JSON Files") rebuilds and publishes to GitHub Pages.- Scripts query the GitHub Search API:
org:INESCTEC topic:<project_topic>;update_projects.pykeeps the top 3 repos by stars and merges their topics intoproject_tags. - Both scripts read the token from the
GH_TOKENenv var. In CI it is the built-insecrets.GITHUB_TOKEN(auto-issued per run, never expires). Do not switch back to a PAT secret: the oldGH_TOKENPAT expired in Oct 2026 and silently zeroed every project. Never hardcode a token. - Scripts exit non-zero on any API error, so a failed refresh never commits or deploys;
auto-deploy.ymlonly runs when the update workflow succeeded. To run locally:GH_TOKEN=$(gh auth token) python scripts/update_projects.py. Running locally is rarely needed; trigger the workflow instead. - Because the bot commits to
masteralmost daily, alwaysgit pullbefore committing. Conflicts onprojects.json/areas.jsoncounts should be resolved by taking the remote version (it is regenerated anyway).
src/pages/- route-level components (HomePage, ProjectsPage, NotFoundPage)src/components/- reusable UI components (ProjectCard, AreaCard, Header, etc.)src/assets/- static images and logospublic/- JSON data files and static assets
- Tailwind CSS with custom color palette defined in
tailwind.config.js - Custom colors:
dark-blue,light-blue,energy-yellow,industry-red,def-grey - Global styles and custom utility classes in
src/index.css - Mobile-first responsive design using Tailwind breakpoints
- Ant Design (
antd) for complex components (Popover, tooltips) - FontAwesome and Octicons for icons
- react-scroll for smooth scrolling navigation on HomePage
Public repo. Nothing in it may contain a credential.
- No tokens in code or committed files. Scripts read
GH_TOKENfrom the env; CI passes the built-inGITHUB_TOKEN. Locally:GH_TOKEN=$(gh auth token) .... - Secret scanning runs in two layers with the same tool and baseline (
detect-secrets1.5.0,.secrets.baseline):- local:
.pre-commit-config.yaml(each clone must runpre-commit installonce) - CI:
.github/workflows/secret-scan.ymlon every push / PR
- local:
- A false positive is added with
detect-secrets scan --baseline .secrets.baselineand thendetect-secrets audit .secrets.baseline; never by disabling the hook. - Workflows declare explicit least-privilege
permissions:. Action/npm updates come via.github/dependabot.yml. - If a secret is ever committed: revoke it first (rewriting public history does not un-leak it), then remove it from the code.
- Add an entry to
/public/projects_input.json:{ "project_area": "Energy", "project_name": "My Project", "project_logo": "myproject.png", "project_website": "https://... or null", "project_description": "...", "project_topic": "myproject", "project_tags": ["Energy"] }project_areamust be one of the areas inareas.json.project_tagsis replaced by the repos' GitHub topics;top_repositories,total_starsandtotal_repositoriesare added by the script. - On GitHub, add the topic
<project_topic>to every INESCTEC repo belonging to the project. Without it the project shows zero repos. - Put the logo in
src/assets/with the exact filename used inproject_logo(or usenull). - Optional: to feature it on the home page, add
{ "project_name", "project_topic", "project_logo" }to that area'sfeatured_projectsin/public/areas.json. git pull, commit, push tomaster. The workflow regeneratesprojects.jsonand redeploys.