How tskaigi/hokuriku-web-site works
Project type and purpose
• This is a full-stack static web application (an event site) built with Next.js 13’s App Router.
• It uses SSG (static site generation) + a custom data-generation script (scripts/generate-talks-json.ts) to produce JSON at build time.
• Hosting/deployment is handled via Firebase Hosting (and GitHub Actions for CI/CD), serving only static assets—no runtime backend.
File structure
• Top level:
• config files (next.config.ts, .firebaserc, firebase.json, GitHub Actions workflows)
• scripts/ – custom build-time scripts
• public/ – static assets (images, OGP cards)
• src/app/ – Next.js App Router pages/layouts
• src/components/ – React components, organized by domain (talks, sponsors, UI primitives)
• src/constants/ & src/utils/ & src/hooks/ & src/lib/ – domain data and helpers
• CI/CD: .github/workflows/ci.yml (build + tests), cd.yml (deploy to production), preview.yml (deploy preview to Firebase).
Key README insights
• Uses pnpm package manager
• Prettier and linting enforced on PRs
• GitHub Actions automatically builds and deploys preview URLs to Firebase Hosting
• On merge to main, production deploy occurs
Main components and interactions
a. Components
• Developer Workstation (code + local build)
• GitHub Repository
• CI/CD Pipelines (GitHub Actions)
– Build job: pnpm install → pnpm run build (Next.js + JSON script)
– Preview job: deploy to Firebase Preview channel
– Release job: deploy to Firebase Production
• Firebase Hosting (CDN + edge cache)
• Client Browser
• Next.js Static Artifacts
– HTML/CSS/JS pages (App Router output)
– JSON data (generated in public/)
– Public static assets (SVGs, OGP images, etc.)
b. Relationships & data flow
1. Developer pushes code → GitHub
2. GitHub Actions triggers CI → installs → runs build script → outputs artifacts
3. Artifacts → deployed to Firebase Preview (for PR) or Production (on main)
4. End user’s browser requests URL → Firebase CDN edge → serves static HTML/CSS/JS/JSON → browser renders pages
c. Architectural patterns & principles
• Static-First / SSG: all pages are pre-rendered at build time
• Component-Based UI: React components organized by domain
• Separation of concerns: content in src/constants, UI in src/components, routing in src/app
• CI/CD as part of architecture—automated preview and release channels
d. Relevant technologies
• Next.js 13 (App Router + SSG)
• React + TypeScript
• pnpm
• Firebase Hosting (with .firebaserc and firebase.json)
• GitHub Actions (ci.yml, cd.yml, preview.yml)
• Prettier & ESLint
Diagramming recommendations
– Blue for code & CI/CD
– Green for hosting & CDN
– Orange for static artifacts
– Gray for client
Key points to capture
• That there is no dynamic backend at runtime—all pages and data are pre-built
• The multi-stage pipeline: local → GitHub → preview → prod
• Static asset flow from public/ and JSON generation
• Firebase Hosting as the sole serving layer
• React/Next.js App structure (pages in src/app, domain components)