Architecture
This document outlines the high level architectural design for SSN API.
Last updated
Was this helpful?
This document outlines the high level architectural design for SSN API.
Last updated
Was this helpful?
The social service network (SSN) provides an efficient API for interacting with social services in our graph database.
Social services in the SSN database was modeled after the schema. The Human Services Data Specification (HSDS) is core data exchange format. HSDS is designed to support the publication of open, interoperable community resource directory data.
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:
organization - that provide services;
service - that have descriptions, classifications and other information to allow potential service users to identify those services that can meet their needs;
location - where services are delivered - either physically, or virtually (over the phone or Internet);
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.
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:
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.
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
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.
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.
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.
We are using the following tech stack for SSN API:
Programming Language: JavaScript
Frameworks: Nodejs and Express
In-memory Cache: Redis
Custom Neo4j graph databases are hosted on GCP for both production and staging environments.
Note: You'll need a password and username to access the Neo4j browsers. You can get configurations and password details from your tech lead.
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:
Cd into project folder and Install packages using yarn.
Get the .env files from your tech lead and add to your project folder.
Start the application locally:
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/graphqlin your browser to use the Apollo Studio.
Due to the slight variation in application, we adapted and modified the HSDS schema slightly as suggested , in order to accommodate our use case and more importantly our architecture.
To view and use the SSN API, visit the Graphql playground , you can also understand what fields are used from the
Core Database: , Mongo Db
Staging Instance: Hosted under the name , and you can access the staging graph browser .
Production Instance: Hosted under the name , and you can access the production graph browser
The SSN API is hosted on Heroku under the pipeline name. We have two hosted instances for both staging and production environment.
Staging: The staging environment is hosted under the name . It is directly linked to the branch on the GitHub repository. Heroku CI/CD has been configured to automatically run tests and deploy a new version on every push to branch.
Production: The production environment is hosted under the name . It is directly linked to the branch on the GitHub repository. Heroku CI/CD has been configured to automatically run tests and deploy a new version on every push to branch.
For developer resources go
