How opensource-construction/osc-directory works
Project type and purpose
• This is a full-stack, monorepo web application whose purpose is to provide a curated directory of open-source Architecture, Engineering, and Construction (AEC) projects.
• The README confirms that contributors submit new entries via GitHub issues, and the live site is a SvelteKit frontend.
File structure
• Top level:
• .github (issue templates & GitHub Actions workflows)
• backend (Node.js/TypeScript scripts, data store, tests)
• frontend (SvelteKit UI, server routes, Firebase config)
• shared (TypeScript types & category definitions)
• The backend folder contains:
• data/projects.json (the canonical data store)
• helpers & utils (extraction, validation logic)
• scripts (ETL: parse issues, update metadata, generate README tables)
• tests/ (unit tests for parsing & validation)
• The frontend folder contains:
• Svelte components under src/lib/components
• a serverless API endpoint at src/routes/api/projects/+server.ts
• Firebase hosting/rewrites in firebase.json
• shared holds cross-cutting definitions (categories.ts, types/index.ts) used by both front and back end.
Main components and interactions
a. GitHub (Issues & Actions)
– Contributors open or modify issues using the .github/ISSUE_TEMPLATE forms.
– GitHub Actions (workflows) validate new submissions automatically.
b. Backend ETL service (Node.js/TypeScript)
– scripts/parse-issue.ts reads GitHub issue payloads (via local clones or API).
– helpers/validation.ts ensures fields are correct.
– scripts/update-metadata.ts and generate-readme-tables.ts rebuild data/projects.json and update README.md.
c. Data Layer (JSON in backend/data)
– projects.json is the single source of truth.
– projects.backup*.json are snapshots for recovery.
d. Shared library (shared/)
– categories.ts and types/index.ts ensure type safety and consistent enums across front and back ends.
e. Frontend UI (SvelteKit)
– The server route at /api/projects loads the JSON data (either by requiring the file or via a build-time import).
– Svelte components render ProjectList, filters, search bar, and individual ProjectCard.
– Styling and layout in app.css and +layout.svelte.
f. Deployment (Firebase Hosting/Functions)
– frontend/firebase.json and .firebaserc configure hosting & rewrites.
– GitHub Actions in .github/workflows may deploy the frontend on each push.
Architectural patterns and design principles
• Monorepo with two logical workspaces (backend & frontend) plus shared code.
• ETL-style backend: discrete scripts form a pipeline from GitHub issues → validated JSON → updated markdown and data.
• SvelteKit serverless pattern: bundling API and UI in the same project.
• Type safety and DRY enforced via shared TypeScript definitions.