Developer Docs

A technical description of how Ecologic works under the hood and an API guide for fellow ecohackers

Technology Description

The Ecologic software platform comprises five components:

  • the client (either web or mobile), which provides a user interface with the web platform
  • the web servers, which receive and process external requests, while updating the state of the various internal processes.
  • the databases and datastores, which store the current state of the application
  • the analytics queues, which provide a record of all outstanding simulation tasks
  • the analytics servers, which pull simulation jobs off the analytics queue, perform a range of geometrical, physical and financial algorithms, and then return a set of results to the datastore for subsequent processing and storage

The server infrastructure applies a scalable application architecture, using Amazon Web Services. There are at least two web servers available at all times, with incoming requests distributed using a load balancer. The web servers support autoscaling, which means they may be automatically replicated to meet large amounts of user traffic. Similarly, there are several analytics server instances available at all times, each with multiple cores, allowing a large number of simulations to be performed concurrently. The number of available analytics servers available at a given time is autoscaled to meet incoming simulation requests. The load on the web server and analytics server resources is monitored at all times, with automated notifications sent to our team in the event that the servers are overloaded.

The client, web servers and analytics server code is deployed using continuous integration and testing. When source code revisions are pushed to the source control system, images are automatically built within the source control system and a full test suite is performed to ensure the new build performs as expected, including static code analysis, dynamic unit testing and system integration / functional browser testing. When desired, these images may be directly deployed to our platform, which subsequently rotates the images. This deployment system allows for rapid continuous integration of software improvements throughout the day while maintaining availability. The system also allows us to minimise the attack surface of the web platform, providing a high level of security to incursion.

The client, web servers and analytics servers all have automated uptime, response time and error monitoring in place. If an error is raised by the client or by any of the servers, an error report is automatically sent to an independent web service, which forwards the error report to the relevant staff member responsible for that code. Telemetry installed in the app and servers can then be applied to replay, replicate, diagnose and resolve any errors without user intervention. The platform is also monitored by an independent service monitoring availability and performance at all times, with alerts sent to our team in the event of an unscheduled downtime.

The software is designed for rapid disaster recovery in the unlikely event of a catastrophic failure. Database backups are continuously captured and stored on an independent storage service and the complete application can be restored in a matter of minutes.

    API Reference

    A set of APIs have been provided to allow you to integrate our software with a range of external software systems.

      Notification API

      The Notification API provides a one-way computer-to-computer interface to automatically notify partners and/or suppliers when specific events occur on the Ecologic platform.

      Some common use cases include:

      • automatically create a contact in your CRM when a user profile is created
      • automatically generate project leads in your CRM tool when a project is created on the platform

      The Notification API provides a webhook interface to provide maximum flexibility to partners and suppliers. After specifying the notification type as 'webhook' and providing a webhook URI, the platform will send the requested data as JSON.

      For a library of easily configurable webhook integrations with most popular off-the-shelf CRM tools we recommend Zapier. For high volume or custom integrations we recommend either developing the integration yourself on AWS Lambda or commissioning us to help you.

      Available events

      Event Description
      Audit:Create the creation of an audit
      Audit:Simulate the simulation of an audit
      Audit:Assign the assignment of an audit to a different user
      Audit:Label:Apply the assignment of a new status label to an audit
      RequestQuote:Create the creation of a new quote request
      RequestQuote:Label:Apply the assignment of a new status label to a quote request

      The following table provides a field set description for RequestQuote:Create

      Field Description
      action action code e.g. 'solar_pv'
      supplier_name supplier name e.g. 'ACME products'
      offer_title offer code e.g. '3 kW Standard Solar Package'
      offer_description offer description
      offer_price price listed against the product or service requested by the customer
      first_name customer first name as string
      last_name customer last name as string
      street customer street address as a combined string
      postcode customer address postcode component
      state customer address state component
      country customer address country component
      reply_email reply email address provided by the customer
      reply_phone reply phone number provided by the customer
      comments comments provided by the customer

        Management API

        The Management API provides a two-way computer-to-computer interface for partners to directly query, create and update records in the Ecologic platform without using the web client. Some use cases include:

        • querying data collected by the platform
        • querying actions and impacts arising from the platform
        • updating the status of projects when updates are made on external CRM software

        HMAC is applied for authentication, security and data integrity. Valid URLs must include an 8-byte random hex nonce ("_"), an ISO formatted expiry datetime ("expiry") and signature ("sig"). The HMAC signature uses a SHA256 hash and 64 byte encoding.

        API keys may be generated / revoked by team admins via the team admin console.

        A set of Zapier integrations have been developed to allow the most common actions to be readily implemented.

        Available actions

        Action Endpoint