Citizens are watching

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
  • Migrating away from: Google Sheets
  • Migrating to: Politigraph
• 🤝 Contributing Guideline
• 📜 License

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

Currently pausing due to the backend migration

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

• Yarn v1 as a package manager
• Husky and lint-staged will
  • Lint (ESLint) and format (Prettier) code before committing
  • Validate that commit message is aligned 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

• 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. We are pausing staging CI/CD pipeline in GitHub Action due to the failed build during new data backend migration.
• Production: The Github Actions Workflow can only be manually triggered to download the latest build artifact and upload to our server through SSH.

Start the project in development mode

yarn dev

to see/develop custom components from Histoire's stories

yarn story:dev

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.

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.

• /_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

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.

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

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

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

• 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

We are migrating away from Google Sheets to our new political GraphQL service called "Politigraph". The data that are completely migrated are:

• Politicians
• Political Parties
• Assemblies
• Vote Events
• Bills
• Promises

Data is pre-process server-side during the Static Site Generation (SSG) build step as following

flowchart TD
    B[Google Sheets] --> |Fetched, validated, parsed| C(Sheethuahua)
    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 available at our public Google Sheets
• lib/datasheets provides functions using Sheethuahua to fetch, validate, and parse data from Google Sheets.
• The src/models 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 fetched from the client-side.

Politigraph is a Thai politics graph database using GraphQL and Neo4j. Fully migrated to this will allow us to run Parliament Watch in SSR mode, requesting data from Politigraph in real-time.

flowchart TD
    B[Politigraph's GraphQL] --> |fetched by| C(GenQL's generated client)
    C --> |used in| D(Svelte's routes)
    D --> |Svelte SSR| 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(SvelteKit SSR Website)

• We use GenQL to generate type-safe GraphQL client, communicating with Politigraph GraphQL endpoint

Please read CONTRIBUTING.md

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.