Architecture

This document outlines the high level architectural design for SSN API.

The social service network (SSN) provides an efficient API for interacting with social services in our graph database.

Schema

Social services in the SSN database was modeled after the Human Service Data API (HSDS) schema. The Human Services Data Specification (HSDS) is Open Referral’s core data exchange format. HSDS is designed to support the publication of open, interoperable community resource directory data.

Why use HSDS?

HSDS is designed to support bulk exchange of data between different information and referral systems. It is appropriate to use when:

• You want to export a collection of information about services, the locations where they can be accessed, and the organizations that deliver them.

• HSDS as a reference model when designing a data system to store or exchange human service information.

HSDS has been designed around the core required fields to support search and discovery of services, and the recommend fields that are useful to a wide range of users. Individual implementations may extend HSDS with their own properties.

HSDS supports four core tables which are:

1. organization - that provide services;

2. service - that have descriptions, classifications and other information to allow potential service users to identify those services that can meet their needs;

3. location - where services are delivered - either physically, or virtually (over the phone or Internet);

4. service_at_location - a link table used to record where particular services are available, and to over-ride any default service or location information, with information specific to the service at a specific location.

Below is the ER diagram of the HSDS.

SSN derived schema

Due to the slight variation in application, we adapted and modified the HSDS schema slightly as suggested here, in order to accommodate our use case and more importantly our architecture.

Our architecture uses a knowledge graph (Neo4j) as our main database for storing services. Knowledge graphs are more useful and flexible when we have flat data structures, and this is not the case when working with the default HSDS schema, hence the main reason for adaptability.

Our graph schema has 7 main nodes as shown in the following image:

1. Organization: An Organization is the parent/highest node in our graph network, and from this node. This contains all details about a service provider, including metadata like name, tagline, description, and so on. See full schema here.

2. Service: A service node is directly connected to an organization, and do not exist without one. Services are human-service provided by organizations, and they include metadata about the particular service like description, service provided, area covered and so on. See full schema here. t

3. Location: Location can be connected to the organization or service node. Services and Organizations can have multiple locations. A location node contain properties like zip code, latitudes and longitudes, address and so on. See full schema here.

4. Contact: A contact node represent a person in an organization or service. Contact contains metadata about people, and include metadata like name, title, and so on. See full schema here.

5. Phone: A phone node contains phone details about an organization or service. Organizations and Services can have more than one phone. See full schema here.

SSN API

To view and use the SSN API, visit the Graphql playground here, you can also understand what fields are used from the schema key page.

Technology Stack

We are using the following tech stack for SSN API:

• Programming Language: JavaScript

• Frameworks: Nodejs and Express

• Core Database: Neo4j graph db, Mongo Db

• In-memory Cache: Redis

Devops and Hosting

SSN Database

Custom Neo4j graph databases are hosted on GCP for both production and staging environments.

• Staging Instance: Hosted under the name neo4j-instance-1, and you can access the staging graph browser here.

• Production Instance: Hosted under the name ssn-neo4j-prod-instance, and you can access the production graph browser here.

Note: You'll need a password and username to access the Neo4j browsers. You can get configurations and password details from your tech lead.

SSN API hosting

The SSN API is hosted on Heroku under the pipeline name ssn-services. We have two hosted instances for both staging and production environment.

• Staging: The staging environment is hosted under the name ssn-services-staging. It is directly linked to the dev branch on the GitHub repository. Heroku CI/CD has been configured to automatically run tests and deploy a new version on every push to dev branch.

• Production: The production environment is hosted under the name ssn-services-prod. It is directly linked to the main branch on the GitHub repository. Heroku CI/CD has been configured to automatically run tests and deploy a new version on every push to main branch.

Development environment setup

For developers, to set up a local environment, follow the steps below:

• Ensure you have Nodejs (v12 and above), Yarn and Git installed.

• Clone the repository:

git clone https://github.com/PhilanthroLab/SSN-Services

• Cd into project folder and Install packages using yarn.

cd SSN-Services
yarn 

• Get the .env files from your tech lead and add to your project folder.

• Start the application locally:

yarn start

• By default, your application starts on port 3001. Open your browser to localhost:3001, and you should see a page like the one below:

We use Graphql for our APIs, as such you can visit localhost/graphql in your browser to use the Apollo Studio.

For developer resources go here