diff --git a/SYSTEM_DESIGN.md b/SYSTEM_DESIGN.md new file mode 100644 index 000000000..8654c7526 --- /dev/null +++ b/SYSTEM_DESIGN.md @@ -0,0 +1,56 @@ +# System Design + +## Table of Contents +- [Components](#components) +- [Process Flow](#process-flow) +- [Integration](#integration) + +## Components + +The following diagram illustrates the major components in the VinylDNS ecosystem and the external systems they interact with. + +![VinylDNS Architecture Diagram](img/VinylDNS_overview.png) + +* API - RESTful endpoints to allow interaction with VinylDNS + +* Database - stores information that the VinylDNS application needs + +* DNS servers - communicates DNS changes and resolves DNS records + +* Message queue - temporarily stores DNS requests for processing + +* LDAP Service - application protocol used to authenticate user access to the VinylDNS portal + +* Portal - graphical user interface to interact with the VinylDNS API + +* Tooling - external libraries and utilities used to interact with the VinylDNS API + +## Process Flow + +1. LDAP service authenticates user credentials and grants access to the portal. +1. If the user is accessing the portal for the first time, VinylDNS credentials are generated and stored. +1. User navigates portal or uses integration tooling to generate a signed API request. +1. When the API receives a request, it loads the credentials for the calling user from the database and validates the request signature to ensure that the request was not modified in transit. +1. The request is then validated to ensure that: + - the request data is correct + - the request passes all validation checks + - the user has access to make the change +1. Assuming the request is in good order, the request is put on a message queue for handling. +1. One of the VinylDNS API server instances pulls the message from the queue for processing. For record changes, a DDNS message is issued to the DNS backend server. +1. When the message completes processing, it is removed from the message queue. The changes are applied to the VinylDNS database along with an audit record for the request. + +## Integration + +Integrating with VinylDNS is simple since each API endpoint is effectively a distinct DNS operation (eg. create record, update record, delete record, etc.). The only requirement for sending a request is generating the correct AWS SIG4 signature without content length and providing the corresponding HTTP headers so that VinylDNS can verify it. See [API Authentication](https://www.vinyldns.io/api/auth-mechanism.html) for more details. + +The current tooling available to perform VinylDNS API requests include: + +* [go-vinyldns](https://github.com/vinyldns/go-vinyldns) - Golang client package + +* [vinyldns-cli](https://github.com/vinyldns/vinyldns-cli) - command line utility written in Golang + +* [vinyldns-java](https://github.com/vinyldns/vinyldns-java) - Java client + +* [vinyldns-python](https://github.com/vinyldns/vinyldns-python) - Python client library + +* [vinyldns-ruby](https://github.com/vinyldns/vinyldns-ruby) - Ruby gem diff --git a/img/VinylDNS_overview.png b/img/VinylDNS_overview.png new file mode 100644 index 000000000..b673b0778 Binary files /dev/null and b/img/VinylDNS_overview.png differ