# opensource-construction/osc-directory architecture

> Architecture diagram of the GitHub repository opensource-construction/osc-directory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opensource-construction/osc-directory
- Repository: https://github.com/opensource-construction/osc-directory

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Contributors & GitHub"
        direction TB
        Contributor["Contributor"]:::external
        IssueTemplates["GitHub Issue Templates"]:::external
        GitHubActions["GitHub Actions Workflows"]:::external
    end

    subgraph "Backend ETL & Data"
        direction TB
        ParseIssue["parse-issue.ts"]:::backend
        ValidateIssue["validate-issue-project.ts"]:::backend
        AddIssue["add-issue-project.ts"]:::backend
        UpdateMetadata["update-metadata.ts"]:::backend
        GenerateTables["generate-readme-tables.ts"]:::backend
        ValidationHelper["validation.ts"]:::backend
        ExtractionHelper["repo-extraction.ts"]:::backend
        DataStore[(projects.json)]:::data
        Backup1[(projects.backup.json)]:::data
        Backup2[(projects.backup.1750269373280.json)]:::data
        SharedCategories["categories.ts"]:::shared
        SharedTypes["types/index.ts"]:::shared
    end

    subgraph "Frontend & Deployment"
        direction TB
        API["+server.ts (Projects API)"]:::frontend
        Layout["+layout.svelte"]:::frontend
        PageComp["+page.svelte/+page.ts"]:::frontend
        DirectoryHeader["DirectoryHeader.svelte"]:::frontend
        ProjectList["ProjectList.svelte"]:::frontend
        ProjectCard["ProjectCard.svelte"]:::frontend
        ProjectSorting["ProjectSorting.svelte"]:::frontend
        MetadataFilter["MetadataFilter.svelte"]:::frontend
        Nav["Nav.svelte"]:::frontend
        Footer["Footer.svelte"]:::frontend
        SearchBar["SearchBar.svelte"]:::frontend
        PlatformFilters["PlatformFrameworkFilters.svelte"]:::frontend
        AppCSS["app.css"]:::frontend
        AppHTML["app.html"]:::frontend
        FirebaseConfig["firebase.json/.firebaserc"]:::external
    end

    %% Connections Contributors -> GitHub
    Contributor -->|"fills template"| IssueTemplates
    IssueTemplates -->|"submits issue"| GitHubActions
    GitHubActions -->|"triggers ETL pipeline"| ParseIssue

    %% ETL pipeline
    ParseIssue -->|"calls"| ValidateIssue
    ValidateIssue -->|"uses"| ValidationHelper
    ParseIssue -->|"uses"| ExtractionHelper
    ValidateIssue -->|"on success"| AddIssue
    AddIssue -->|"updates"| DataStore
    AddIssue -->|"backs up"| Backup1
    AddIssue -->|"backs up"| Backup2
    AddIssue -->|"then"| UpdateMetadata
    UpdateMetadata -->|"regenerates"| GenerateTables
    GenerateTables -->|"writes"| DataStore

    %% Shared library
    SharedCategories --> DataStore
    SharedTypes --> DataStore
    SharedCategories --> ParseIssue
    SharedTypes --> ParseIssue
    SharedCategories --> API
    SharedTypes --> API

    %% Frontend flows
    DataStore -->|"import JSON"| API
    API -->|"fetch()/REST"| PageComp
    PageComp --> Layout
    PageComp --> DirectoryHeader
    PageComp --> ProjectList
    DirectoryHeader --> Nav
    ProjectList --> ProjectCard
    ProjectList --> ProjectSorting
    ProjectList --> MetadataFilter
    Layout --> SearchBar
    Layout --> PlatformFilters
    AppCSS --> Layout
    AppHTML --> Layout
    PageComp --> Footer

    %% Deployment
    PageComp -->|"deploy"| FirebaseConfig
    FirebaseConfig --> PlatformFilters

    %% Click events
    click IssueTemplates "https://github.com/opensource-construction/osc-directory/tree/main/.github/ISSUE_TEMPLATE"
    click GitHubActions "https://github.com/opensource-construction/osc-directory/tree/main/.github/workflows"
    click DataStore "https://github.com/opensource-construction/osc-directory/blob/main/backend/data/projects.json"
    click Backup1 "https://github.com/opensource-construction/osc-directory/blob/main/backend/data/projects.backup.json"
    click Backup2 "https://github.com/opensource-construction/osc-directory/blob/main/backend/data/projects.backup.1750269373280.json"
    click ParseIssue "https://github.com/opensource-construction/osc-directory/blob/main/backend/scripts/parse-issue.ts"
    click ValidateIssue "https://github.com/opensource-construction/osc-directory/blob/main/backend/scripts/validate-issue-project.ts"
    click AddIssue "https://github.com/opensource-construction/osc-directory/blob/main/backend/scripts/add-issue-project.ts"
    click UpdateMetadata "https://github.com/opensource-construction/osc-directory/blob/main/backend/scripts/update-metadata.ts"
    click GenerateTables "https://github.com/opensource-construction/osc-directory/blob/main/backend/scripts/generate-readme-tables.ts"
    click ValidationHelper "https://github.com/opensource-construction/osc-directory/blob/main/backend/helpers/validation.ts"
    click ExtractionHelper "https://github.com/opensource-construction/osc-directory/blob/main/backend/helpers/repo-extraction.ts"
    click SharedCategories "https://github.com/opensource-construction/osc-directory/blob/main/shared/categories.ts"
    click SharedTypes "https://github.com/opensource-construction/osc-directory/blob/main/shared/types/index.ts"
    click API "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/routes/api/projects/+server.ts"
    click Layout "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/routes/+layout.svelte"
    click PageComp "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/routes/+page.svelte"
    click PageComp "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/routes/+page.ts"
    click DirectoryHeader "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/lib/components/directory/DirectoryHeader.svelte"
    click ProjectList "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/lib/components/directory/ProjectList.svelte"
    click ProjectCard "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/lib/components/directory/ProjectCard.svelte"
    click ProjectSorting "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/lib/components/directory/ProjectSorting.svelte"
    click MetadataFilter "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/lib/components/directory/MetadataFilter.svelte"
    click Nav "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/lib/components/ui/Nav.svelte"
    click Footer "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/lib/components/ui/Footer.svelte"
    click SearchBar "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/lib/components/ui/SearchBar.svelte"
    click PlatformFilters "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/lib/components/ui/PlatformFrameworkFilters.svelte"
    click AppCSS "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/app.css"
    click AppHTML "https://github.com/opensource-construction/osc-directory/blob/main/frontend/src/app.html"
    click FirebaseConfig "https://github.com/opensource-construction/osc-directory/blob/main/frontend/firebase.json"
    classDef external fill:#a2cffe,stroke:#333,stroke-width:1px
    classDef backend fill:#c2f0c2,stroke:#333,stroke-width:1px
    classDef frontend fill:#ffd699,stroke:#333,stroke-width:1px
    classDef data fill:#fdd7e4,stroke:#333,stroke-width:1px
    classDef shared fill:#e2d5f9,stroke:#333,stroke-width:1px
```
