Skip to content

Latest commit

 

History

History
114 lines (61 loc) · 4.09 KB

ARCHITECTURE.md

File metadata and controls

114 lines (61 loc) · 4.09 KB
Raw

Architecture of Big Cases Bot 2

CourtListener API

Big Cases Bot 2 uses CourtListener's REST API to receive news about new filings. It does this via webhooks. When CourtListener learns about a new docket entry in a followed case, CourtListener will POST a webhook to BCB2 with information about the docket entry and documents associated with it.

Database

BCB2 uses a Postgres database to keep track of cases and documents it knows about.

Posting

BCB2 posts to Twitter (@big_cases), Mastodon (@big_cases@law.builders), and Bluesky (@bigcases.bots.law).

Interacting via social media

  • For now, you can't @-mention the bots, but it's being tracked in issue #28.

Developer Installation

To set up a development machine, do the following:

  1. Clone the bigcases2 repository.

  2. Create a personal settings file. To do that, copy-paste the .env.example file to .env.dev.

  3. Modify your new .env.dev file and uncomment the line ALLOWED_HOSTS="*"

  4. Next, create the bridge network that docker relies on:

    docker network create -d bridge --attachable bc2_net_overlay

    This is important so that each service in the compose file can have a hostname.

  5. cd into bigcases2/docker/bigcasesbot, then launch the server by running:

    docker compose up -d --build

  6. Once that's done, it'll be up at http://localhost:8888 (note the port; it's different than normal)

Command Line Interface

  1. Generate some dummy data for your database:

     docker exec -it bc2-django python manage.py bootstrap-dev

  2. Lookup specific data from CourtListener:

     docker exec -it bc2-django python manage.py lookup 64983976

    This will use CL API to lookup the Docket 64983976and output its data in the console. This command also accepts the following command line options:

    • --add: saves the case in the database
    • --subscribe: creates a CourtListener docket alert subscription

  3. Post something manually in the registered channels:

     docker exec -it bc2-django python manage.py post

  4. Create mastodon subscription to push notifications:

     docker exec -it bc2-django python manage.py mastodon-subscribe

    This command requires that the following variables are set in the .env file: MASTODON_SHARED_KEY, MASTODON_PUBLIC_KEY, MASTODON_PRIVATE_KEYand HOSTNAME. We added a script to generate the first three variables. Execute the following command to use the script and paste the result in your .env file:

     docker exec -it bc2-django python /opt/bigcases2/scripts/get-mastodon-keys.py

    Make sure that the MASTODON_TOKEN and MASTODON_SERVER are set before using the previous command.

  5. Delete mastodon subscription to push notifications:

     docker exec -it bc2-django python manage.py mastodon-unsubscribe

Server

What does the server do?

  • Receives webhooks from CourtListener, Twitter, and Mastodon
  • Processes new documents from CourtListener (generate thumbnails, create posts, post)

Incoming webhooks

  • /webhooks/docket-[secret]: From CourtListener, delivered when there is a new document in a followed case. The full URL is secret.
  • /webhooks/twitter: From Twitter, Account Activity API
  • /webhooks/mastodon: From Mastodon instance, Web Push API

Images

BCB2 generates images of the first few pages of a document by using Doctor.

Key Dependencies

External Packages

  • Nginx: web proxy/server
  • Docker (for Doctor)