{"id":25944965,"url":"https://github.com/path-check/scoring-service","last_synced_at":"2026-05-11T15:17:34.222Z","repository":{"id":57539387,"uuid":"283626649","full_name":"Path-Check/Scoring-Service","owner":"Path-Check","description":"This is the Repository for the Scoring Service","archived":false,"fork":false,"pushed_at":"2020-08-31T17:55:30.000Z","size":23402,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-06-21T07:51:36.260Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Path-Check.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-29T23:57:24.000Z","updated_at":"2022-08-01T02:33:15.000Z","dependencies_parsed_at":"2022-09-26T18:31:46.091Z","dependency_job_id":null,"html_url":"https://github.com/Path-Check/Scoring-Service","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Path-Check%2FScoring-Service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Path-Check%2FScoring-Service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Path-Check%2FScoring-Service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Path-Check%2FScoring-Service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Path-Check","download_url":"https://codeload.github.com/Path-Check/Scoring-Service/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241810048,"owners_count":20023887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-04T08:20:20.205Z","updated_at":"2026-05-11T15:17:34.148Z","avatar_url":"https://github.com/Path-Check.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Scoring Service\n\nTells mobile app whether or not to notify everyone, whom an infected user has met the last 14 days, if user is infected. It takes a Summary of Exposures for a given `config.json` (which changes based on health authority) and returns array of Notifications if certain scoring criteria are met.\n\n# General Flow\n\n1. App gets `config.json` from AWS S3 or GCP Cloud Storage bucket.\n\n[Scoring v1 algorithm](https://developer.apple.com/documentation/exposurenotification/enexposureconfiguration/calculating_the_exposure_risk_value_in_exposurenotification_version_1) has this config:  \nhttps://cdn.projectaurora.cloud/cfg/v1.config.json  \nhttps://cdn.projectaurora.cloud/dev/cfg/v1.config.json\n\n[Scoring v1.6 algorithm](https://developer.apple.com/documentation/exposurenotification/enexposureconfiguration) has this config:  \nhttps://cdn.projectaurora.cloud/cfg/v1.6.config.json  \nhttps://cdn.projectaurora.cloud/dev/cfg/v1.6.config.json\n\n2. App passes configuration to GAEN API\n3. GAEN runs exposure check and returns ExposureSummary\n4. (If matchedKeyCount: 0, discard, done)\n\n5. App constructs modified ExposureSummary object using structure from /v1/scoring input:\n    1. Adds dateReceived (read comments in definition below)\n    2. timeZoneOffset\n    3. seqNoInDay: this is saying it’s the nth ExposureSummary we received today.\n\n6. App sends new ExposureSummary, stores UnusedExposureSummaries to server\n\nScoring server has this URL:\nhttps://api.scoring.projectaurora.cloud/scoring\n\n7. Server returns Notification array (might be empty) with any new notifications, contains ExposureSummaries on which these notifications were based\n\n8. App:\n    1. Removes any ExposureSummaries from UnusedExposureSummaries that are present in new notifications\n    2. If no new notification: stores new ExposureSummary in UnusedExposureSummaries\n    3. Stores new Notifications if exist\n    4. Displays notifications to users based on new Notification object\n\n### State saved in app:\n\n- Map/dictionary of unused exposure summaries (14 days), keyed by “dateReceived:seqNoInDay”\n- Notification array (14 days)\n- Sequence # for ExposureSummary in day\n\n## Environment\n\n- GAEN v1.0 for now\n- Working with ExposureSummary (not ExposureInfo to avoid direct OS Notifications to users)\n- Must be deployed in Google/AWS/Azure clouds.\n\n## TODO\n\n- [x] Scoring API Design (Lina)\n  - [ ] Add scoring API design for ExposureWindows (Apple version 2) to doc (Lina)\n- [x] Basic Go Implementation (Raymond, David)\n- [ ] Scoring Go Implementation (Lina)\n  - [ ] Finish v1 scoring (Lina)\n  - [X] Make it use `config.json` instead of current hardcoded values (Raymond)\n- [X] Deployment on AWS (Raymond, David)\n- [X] cURL calls for the Mobile team and this document down below (Raymond)\n- [ ] Update Mobile app to use the basic scoring function (Matt?)\n- [X] UnitTests with testing data captured by the mobile team (Raymond)\n- [X] Add basic logger and tests in `/model` and `/logging/aws`. Saves JSON files in `/logs`. (Raymond)\n\n# How to Install in Production\n\n(Raymond, David, please update)\n\n\n### Installation and Setup\n\n    - Install Golang: https://golang.org/\n        - This is necessary to compile and test the go application\n    - Install AWS CLI:https://aws.amazon.com/cli/\n        - This is necessary to deploy resources to AWS\n    - Log Into AWS CLI and configure credentials: https://learn.hashicorp.com/tutorials/terraform/aws-build?in=terraform/aws-get-started\n        - run 'aws configure' and input your account credentials\n        - Configure your AWS access key and secret key with the aws configure command, or just create a file ~/.aws/credentials containing the keys:\n            [default]\n            aws_access_key_id = KEY\n            aws_secret_access_key = KEY\n    - Install Terraform: https://learn.hashicorp.com/tutorials/terraform/install-cli?in=terraform/aws-get-started\n        - This is necessary to provision the necessary infrastructure required to deploy the lambda function\n\n### Run Makefile (with AWS CLI and Terraform installed)\n\n    - cd into the target directory (ex: cd scoring/aws)\n    - run 'make'\n\n[Makefile](https://github.com/Path-Check/Scoring-Service/blob/master/scoring/aws/Makefile) does this:\n1. Destroys infrastructure and deletes `scoring.zip` file and `scoring` build (clean)\n2. Initializes Terraform (init.done)\n3. Gets Golang packages, then compiles a binary (scoring)\n4. Makes `scoring.zip` file from compiled build (scoring.zip)\n5. Applies changes and deploys application (deploy.done)\n6. Runs `curl` command to test our scoring service\n\n## How to run in Development\n\n1. Fork the repo to your GitHub user.\n\n2. Clone to your computer.\n\n```\ngit clone https://github.com/Path-Check/Scoring-Service.git\n```\n\n3. Run (with AWS CLI and Terraform installed)\n\n```\nmake\n```\n\n## Running the Tests\n\n```\ngo test -v ./... (all tests, period)\ngo test -v ./model (only tests in /model)\ngo test -v ./scoring/aws (only tests in /scoring/aws)\n```\n\nWith AWS CLI and Terraform installed:\n```\nmake test\n```\n## [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) Function\n- [See AWS lambda function dashboard](https://console.aws.amazon.com/lambda/home?region=us-east-1#/functions/scoring?tab=monitoring)\n- To manually test lambda function with an input, click **Test** in upper right corner. You may use \"ScoreTest\" or configure your own test event.\n\n## [AWS CloudWatch logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html)\n- [See CloudWatch logs](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:log-groups/log-group/$252Faws$252Flambda$252Fscoring) for our scoring lambda function. Click on or search \"log streams.\"\n- [Run queries on logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_RunSampleQuery.html).\n\n## Important Links and References\n\n- \u003chttps://www.google.com/covid19/exposurenotifications/\u003e\n- \u003chttps://developers.google.com/android/exposure-notifications/exposure-notifications-api\u003e\n- \u003chttps://developer.apple.com/documentation/exposurenotification/enexposureconfiguration\u003e\n- \u003chttps://github.com/google/exposure-notifications-server\u003e\n- \u003chttps://github.com/google/exposure-notifications-verification-server\u003e\n- \u003chttps://blog.google/inside-google/company-announcements/update-exposure-notifications\u003e\n- \u003chttps://blog.google/documents/73/Exposure_Notification_-_FAQ_v1.1.pdf\u003e\n- \u003chttps://www.aphlblog.org/bringing-covid-19-exposure-notification-to-the-public-health-community\u003e\n- \u003chttps://www.reuters.com/article/us-health-coronavirus-britain-tracing-ap/britains-covid-19-app-the-game-changer-that-wasnt-idUSKBN2400YM\u003e\n- \u003chttps://github.com/google/exposure-notifications-server/tree/main/examples/export\u003e\n- \u003chttps://github.com/google/exposure-notifications-server/blob/main/examples/export/testExport-2-records-1-of-1.zip\u003e\n\n## Design Documents\n\n- [Data Format For Data Scoring and Metrics](https://docs.google.com/document/d/18UM5T_8PSZ4mJaRpz0H3UDnwyyta2o_GmxtyI396xYs/edit#heading=h.88dqztbzgbbp)\n- [Study Design and Methods](https://docs.google.com/document/d/1FT4J29c2_k5gBdCf04BN7X9HbLCrN1eNmOu0ehgHZjY/edit)\n- [GAEN Scoring Design](https://docs.google.com/document/d/12vU48fwOcGvIYLR7Y0jnSK_ZIeGvwvvszs6EjG_HHNE/edit#heading=h.bg7iuv59zi1d)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpath-check%2Fscoring-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpath-check%2Fscoring-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpath-check%2Fscoring-service/lists"}