# Architecture 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)](https://docs.openreferral.org/en/latest/hsds/) schema. **The Human Services Data Specification (HSDS)** is [Open Referral’s](https://docs.openreferral.org/) 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. ![](/files/-MW4EplO0zde004ajXpO) ### SSN derived schema Due to the slight variation in application, we adapted and modified the HSDS schema slightly as suggested [here](https://docs.openreferral.org/en/latest/hsds/variations_interoperability/), 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: ![](/files/jxL6ecdTCQBmKfhYtja0) 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](#ssn-derived-schema), you can also understand what fields are used from the [schema key page.](/ssn-api/ssn-schema-keys-and-meaning.md) ### Technology Stack We are using the following tech stack for SSN API: * **Programming Language**: JavaScript * **Frameworks**: Nodejs and Express * **Core Database:** [Neo4j graph db](https://neo4j.com/), 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](https://console.cloud.google.com/compute/instancesDetail/zones/us-central1-a/instances/neo4j-instance-1?project=social-safety), and you can access the staging graph browser [here](http://35.223.78.0:7474/browser/). * **Production Instance:** Hosted under the name [ssn-neo4j-prod-instance](https://console.cloud.google.com/compute/instancesDetail/zones/us-central1-a/instances/ssn-neo4j-prod-instance?project=social-safety), and you can access the production graph browser [here. ](http://34.123.175.114:7474/browser/) > 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](https://dashboard.heroku.com/pipelines/45744afa-2681-4fa8-bde9-28ebabb16c21). We have two hosted instances for both staging and production environment. * **Staging**: The staging environment is hosted under the name [ssn-services-staging](#schema). It is directly linked to the [dev](https://github.com/PhilanthroLab/SSN-GraphDatabase/tree/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](https://github.com/PhilanthroLab/SSN-GraphDatabase/tree/dev) branch. * **Production**: The production environment is hosted under the name [ssn-services-prod](https://dashboard.heroku.com/apps/ssn-services-prod). It is directly linked to the [main](https://github.com/PhilanthroLab/SSN-GraphDatabase/tree/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](https://github.com/PhilanthroLab/SSN-GraphDatabase/tree/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. ```bash cd SSN-Services yarn ``` * Get the `.env` files from your tech lead and add to your project folder. ![](/files/-MW4XRtsPrEnHxsnCTX8) * 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: ![](/files/-MW4Wq6j-uGOzX9u8I_-) > 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](/developer-resources/set-up-local-deploy-for-staging-and-production-envs.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://tech.socialsafety.net/ssn-api/architecture.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.