👀 Parliament Watch

Citizens are watching.

Table of Contents

• ⭐ Goal
• 🌎 Deployment
• 🍱 Tech Stack
  • Front-end
  • Local development
  • CI/CD pipeline
• 💾 Data Source
• 🗃️ Directory Structure
• 🪄 Useful Commands
  • Start SvelteKit
  • Start Histoire
  • Generate a new component
  • Log
• 🍭 Design System
  • Typography
  • Colors
  • Components
  • Icons
• Environment Variables
• 🤝 Contributing Guideline

⭐ Goal

We want to record and visualise 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.

🌎 Deployment

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 component documentation

Local development

• pnpm 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 VS Code users, format on save is enabled and the prettier-vscode extension will be recommended when you open the project.
• Hygen for code generation

CI/CD pipeline

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

💾 Data Source

Parliament Watch fetches data from Politigraph, a civic-initiated open API for Thai political data. We use GenQL to generate a type-safe GraphQL client, which communicates with the Politigraph GraphQL endpoint.

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)

Loading

🗃️ Directory Structure

• /_templates Hygen's code generation templates
• /.husky Husky's git hooks
• /src main source code
  • /components Svelte's components
  • /mocks Mock data while we still do not have a backend
  • /models Main data structures defined with TypeScript interfaces
  • /routes SvelteKit's routes
  • /styles Stylesheets, including the custom Carbon Design System, Tailwind, and fonts
• /static Static assets such as logos

🪄 Useful Commands

Start SvelteKit

Start the project in development mode.

pnpm run dev

Start Histoire

To see and develop custom components from Histoire's stories.

pnpm run story:dev

Generate a new component

For a shared component

pnpm run gen:component

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

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

Log

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

🍭 Design System

The project design system is based on Carbon Design System v10 with some modifications. The custom theme is defined with SCSS in src/styles/carbon/. To reduce development overhead, we compile Carbon-related stylesheets into src/styles/carbon/pre-compiled.css with the pnpm run sass:build command.

Typography

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

Colors

• tailwind.config.js defines utility classes based on color function names according to the Carbon theme (see Figma file).
• SCSS variables, which need to be imported wherever you want to use them:
  • colors.scss defines variables for the full color palette (see Figma file).
  • theme.scss defines variables according to the Carbon theme's color function names (see Figma file).

Components

• Use Carbon Components Svelte.
• We have custom shared components available in src/components/.
  • To see the shared components' stories, open Histoire locally with pnpm run 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 pnpm run gen:component to generate a new component. Do not forget to update the story file for the component documentation.

Icons

• Use Carbon Icons Svelte.
• We have custom icons available in src/components/icons, using the same props as Carbon's icons. They are also available in Histoire.
• See Figma file

Environment Variables

You can customize the Politigraph GraphQL endpoint by setting these environment variables. The default is https://politigraph.wevis.info/graphql.

POLITIGRAPH_URL="GraphQL endpoint URL"

🤝 Contributing Guideline

Please read CONTRIBUTING.md