👀 Parliament Watch

Citizens are watching

Thank you for every contibutors who participated in the HACKTOBERFEST 2023 🎉

Table of Content

• ⭐ Goal
• 🌎 Environments
• 🍱 Tech Stack
  • Front-end
  • Local development
  • Deployment pipeline
• 🪄 Useful Commands
  • Start SvelteKit
  • Start Histoire
  • Generate a new component
  • Log
• 🗃️ Directory Structure
• 🍭 Design System
  • Typography
  • Colors
  • Components
  • Icons
• 💾 Data Pipeline
• 🤝 Contributing Guideline
• 📜 License and Terms of Use

⭐ Goal

We want to record and visualise the Thai parliament information including politicians, assemblies, bills, voting processes, and promises.

This project can be seen as a renovated combination of They Work for Us, Law Watch, and Promise Tracker which aim to support several election era.

🌎 Environments

🍱 Tech Stack

Front-end

• Svelte + SvelteKit
• TypeScript
• Carbon Design System (v10) + Carbon Components Svelte
• TailwindCSS
• Histoire for the components documentation

Local development

• Yarn v1 as a package manager
• Husky and lint-staged will
  • Lint (ESLint) and format (Prettier) code before commiting
  • Validate that commit message is align with conventional commit using commitlint
  • Run svelte-check before pushing
• For VSCode user, format on save is enabled and prettier-vscode extension will be recommended when open the project.
• Hygen for a code generation

Deployment pipeline

• Staging: Each push will trigger the Github Actions Workflow to build the site, upload the build artifact, and deploy on Cloudflare Pages. Can also be triggered manually.
• Production: The Github Actions Workflow can only be manually triggered to download the latest build artifact and upload to our server through SSH.

🪄 Useful Commands

Start SvelteKit

Start the project in development mode

yarn dev

Start Histoire

to see/develop custom components from Histoire's stories

yarn story:dev

Generate a new component

For a shared component

yarn gen:component

src/components/ComponentName/ directory will be created with the following files:

• ComponentName.svelte for the component source code.
• ComponentName.story.svelte for the Histoire's story file. Follow a guide on writing stories.

Log

Server-side logging for data warning and SvelteKit error can be enabled via environment variable process.env.LOG_TARGET by setting it to stdout or file. More details in logger.ts.

🗃️ Directory Structure

• /_templates Hygen's code generation templates
• /.husky Husky's git hooks
• /src main source codes
  • /components Svelte's components
  • /mocks Mock data, while we still don't have backend
  • /models Main data structure defined with TypeScript interface
  • /routes Sveltekit's routes
  • /styles Stylesheets, including custom Carbon Design System, tailwind and fonts
• /static static assets such as logos

🍭 Design System

The project design system is based on Carbon Design System v10 with some modification. Custom theme is defined with scss in src/styles/carbon/. To reduce overhead on development, we compile Carbon related stylesheet into src/styles/carbon/precompiled.css with yarn sass:build command.

Typography

• The utility classes is globally available as declared in typography.scss
• See Figma file

Colors

• tailwind.config.js define utility classes based on color function name according to the Carbon's theme (see Figma file)
• scss variable (need to be imported where you want to use)
  • colors.scss define variable of all color palette (see Figma file)
  • theme.scss define variable according to the Carbon theme's color function name (see Figma file)

Components

• Use Carbon Components Svelte
• We have custom shared component available in src/components/.
  • To see shared components' story, open Histoire in local with yarn story:dev or browse it in the staging/stories
  • See all planned component in Figma file.
• If the component is not yet developed:
  • If the component is used by only a specific route, create it in src/components/route-name-and-sub-route-if-exist/
  • If the component is shared, run yarn gen:component to generate a new component. Don't forget to update a story file for the component documentation.

Icons

• Use Carbon Icons Svelte
• We have customed icon available in src/components/icons, using the same props as Carbon's icon. (Also available in Histoire)
• See Figma file

💾 Data Pipeline

Data is pre-process server-side during the build step as following

flowchart TD
    A[Google Sheets] -->|d3 fetch: fetch and parse| B(JS objects)
    B --> |Zod: validate and transform| C(Type-safe objects)
    C --> |used in| D(Svelte's routes)
    D --> |Svelte SSR/SSG| E(dev/prod website)
    C --> |used in| G(Scheduled GitHub Action)
    F(External data source) --> |fetched by| G
    G --> |build| H(JSON on GitHub Page)
    H --> |fetched by| E(GitHub Page)

• Original data is avaiable at our public Google Sheets
• lib/datasheets provides fetch functions for each tables wrapping d3-fetch and Zod's validation.
• Zod's schema for each data table are defined in src/models which also contains ER Diagram and other TypeScript's interfaces.
• Some data, such as politician ranking from external source, will be updated periodically through scheduled Github Action to reduce unnessesary build-time. The output JSON data is served through Github Pages and can be fetch from the client-side.

🤝 Contributing Guideline

Please read CONTRIBUTING.md

📜 License and Terms of Use

Read more at WeVis's Terms of Use (in Thai)