OrderBook documentation
There are many great README templates available on GitHub; however, I didn't find one that really suited my needs so I created this enhanced one. I want to create a README template so amazing that it'll be the last one you ever need -- I think this is it.
Of course, no one template will serve all projects since your needs may be different. So I'll be adding more in the near future. You may also suggest changes by forking this repo and creating a pull request or opening an issue. Thanks to all the people have contributed to expanding this template!
Use the BLANK_README.md to get started.
The primary goal of this design is to [state the primary goal]. Key objectives include [list specific objectives or criteria]. Here's why:
- Your time should be focused on creating something amazing. A project that solves a problem and helps others
- You shouldn't be doing the same tasks over and over like creating a README from scratch
- You should implement DRY principles to the rest of your life 😄
Identify potential users or describe specific use cases to better understand the needs and expectations of the end-users.
Provide a high-level overview of the system architecture, including components, modules, and their interactions.
Outline the data model, defining key entities, relationships, and attributes. Use an entity-relationship diagram if applicable.
Discuss how the design addresses scalability and performance concerns, including load balancing, caching strategies, and database optimization.
Outline security measures incorporated into the design, such as authentication mechanisms, authorization strategies, and data encryption.
Describe how the system will handle errors and exceptions. Discuss logging mechanisms for debugging and monitoring.
Explain your approach to testing, covering unit testing, integration testing, and any other relevant testing methodologies.
The deployment plan outlines the steps and considerations for deploying the system in different environments, such as development and production. It also highlights the deployment tools used in the process.
Warning: The staging environment is not currently within the scope of this documentation. The decision to exclude staging is based on the potential need for additional product assurance requirements. Staging environment configurations and deployment procedures may be addressed in a future updates. It means also that Behavior-Driven Development(BDD) tests are not also integrated and defined yet.
In the development environment, the focus is on providing an environment that allows developers to test and iterate on the system's features. Deployment may involve local development setups or smaller shared environments.
Deployment Steps:
-
Clone the Repository Locally:
- Open a terminal.
- Run the following command to clone the repository:
git clone https://github.com/your/repository.git
-
Local Development Testing with Docker Compose:
- Navigate to the project directory:
cd your_project_directory - Run the following command to launch the system with necessary dependencies:
docker-compose up
- Navigate to the project directory:
Debugging with Docker: If you intend to run Docker in debug mode within the provided development stack, it's important to note that there is currently no specific configuration for executing your Docker image in debug mode. However, it is recommended to explore Delve, a debugger that is well-supported by Docker. Delve facilitates attaching to the executable on demand, providing a useful option for debugging purposes.
Debugging in local: If you plan to run the application with in debug mode within the provided development stack, it's essential to note that there is currently no specific configuration provided. The absence of predefined user settings allows developers to use their own preferences for debugging. It is recommended to explore your preferred debugging tools and configurations to ensure that debugging experience is tailored to your needs.
Deploying to the production environment involves a careful and controlled process to ensure system stability and minimal downtime.
Deployment Steps:
- Code is pushed to the master branch and tagged for release.
- CI/CD tools automate the build, test, and deployment process.
- Container orchestration tools like Kubernetes is employed for managing production containers.
- Blue-Green or Canary deployment strategies may be used to minimize the impact on end-users.
- Monitoring tools, such as Prometheus or Grafana, are employed to track system performance and health.
- Rollback procedures are in place in case of unexpected issues during deployment.
- Docker: Used for containerization and consistent deployment across environments.
- Container Orchestration: Kubernetes for managing and scaling containers in production.
- Monitoring: Prometheus and Grafana for monitoring system performance.
- Infrastructure as Code (IaC): Terraform or Ansible for managing and provisioning infrastructure.
This section should list any major frameworks/libraries used to bootstrap your project. Leave any add-ons/plugins for the acknowledgements section. Here are a few examples.
This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.
This is an example of how to list things you need to use the software and how to install them.
- npm
npm install npm@latest -g
- Get a free API Key at https://example.com
- Clone the repo
git clone https://github.com/your_username_/Project-Name.git
- Install NPM packages
npm install
- Enter your API in
config.jsconst API_KEY = 'ENTER YOUR API';
-
Add Design Documentation
-
Add Technical Documentation
- Add README
- About the project
- Environment prerequisites
- How to install the application
- How to deploy the application
- How to run the application
-
Features
-
As a Market Broker I want to read data from my client
- Add a Reader component which open the file and read line by line
- Add a queue to process asynchrony each line and forward it to the service layer
- Add case where some lines are invalid
- Add case where file doesn't exist
- Add case where the file is empty
-
As a Market Broker I want to process strategy to my client's data
- Process asynchrony each line received from the reader
- Apply strategy to the line
- Forward to the Writer's queue
- Add case where the queue is not created yet
- Add where reader is faster than writer
- Add where writer is faster than reader
-
As a Market Broker I want to transmit computed data to the market
- Add a Writer component which open the file and write line by line
- Add case where file can't be created
- Add case where file doesn't exist
-
As a Developer I want to have idempotent logs whatever my location
- Support for RFC3339 format
- Rolling strategy supported by syslog
-
As a Trader I want to know to use the application
- Add docker file configuration
- Add docker-compose file configuration
- Add documentation for user
-
Add feedbacks
- Known limitations
- Scale design propositions
- Home assignment experience feedback
-
See the open issues for a full list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE.txt for more information.
Adrien Roques - adrien.roques@icloud.com
Project Link: https://github.com/Elbujito/blocktech-bv
In this space, I'd like to acknowledge and credit the following resources that have been instrumental in my learning journey. I've included some of my favorites to get started: