Code Organization

Here are all the important files and folders in the code base, split up by contributor role. You generally shouldn't have to worry about folders outside your role.

Frontend

• .storybook/: Configuration for storybook
• components/: The main source code directory for the frontend. It contains all the UI components, as well as hooks and state management for accessing the database and backend API. Feature and support directories should use camelCase naming, while component directories should use TitleCase.
  • db/: Types and hooks for accessing the Firestore database that drives the whole application. The types are partially duplicated in the cloud functions package (firebase).
• pages/: Configures the routes for the site. Each file corresponds to a route in the site, following Next.js's conventions. Pages should be defined using the createPage helper function to ensure proper layout.
• public/: Stores static assets for the site. A file public/path/to/asset.png is accessible at the URL /path/to/asset.png.
• stories: Contains Storybook stories for our components. Folders are organized by feature/area of the site.
• styles: Contains global styles for the site. Generally styles should be placed in CSS modules next to the component that uses them, or using styled-components.

Backend

• functions/: The main source code directory for the Firebase functions that make up our backend. Folders are organized by feature/resource type. Types are partially duplicated in the components/db module.
  • malegislature.ts: Request methods for accessing the MA Legislature API.
  • scraper.ts: The base scraper that is used to sync data from the MA Legislature API to Firestore
  • auth/: Manages user roles and authorization.
  • profile/: Manages user profiles
  • bills/, cities/, committees/, events/, and members/: Scrapers for specific resources
  • testimony/: Handles testimony submission, edits, and deletions.
  • search/: Syncs data between Firestore and the Typesense search server.
  • testimony/search.ts, bill/search.ts: Resource-specific schemas and syncing logic for Typesense.
• infra/: Configures Kubernetes resources, currently just the Typesense servers.

Operations

• .github/: Configuration for Github Actions workflows
• .vscode/: Configuration for shared VSCode settings
• scripts/: One-off scripts and admin tools for managing the application. In particular, yarn typesense-admin and yarn firebase-admin are cli tools for typesense- and firebase-related things.
• tests/: Integration and system tests for the application, primarily integration tests. Integration tests run in a browser-like environment against a local Typesense server and emulated Firebase services. Start the emulated services with yarn compose up and run the tests with yarn test:integration

Data Science

• analysis/: Notebooks and scripts related to legislative process visualizations and history parsing.