README.md

👀 Parliament Watch

Citizens are watching

Hacktoberfest 2024 is here! every contributor will receive a Parliament Watch sticker ✨ see more

Table of Contents

• ⭐ 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

⭐ 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

Name	URL
Production	https://parliamentwatch.wevis.info
Staging (main branch)	https://parliament-watch.pages.dev

🍱 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 committing
  • 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 custom 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)

Loading

• Original data is available 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 unnecessary 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

Our team is committed to developing all projects as Open Source and releasing data as Open Data under the Attribution-NonCommercial-ShareAlike 4.0 International license. This means the work can be used, adapted, and built upon, but it must not be used for commercial purposes or profit-making. Credit must be given to the original creators, and any derivative work must be shared under the same license as the original. WeVis Ltd. and Punch Up Ltd. are the joint licensors of this license.