ADRS
Using JavaScript to code the application's frontend and backend
- JavaScript is an interpreted lightweight programming language, which significantly reduces the time required for compilation, resulting in faster development cycles.
- JavaScript's simplicity and versatility make it an ideal choice for both frontend and backend development, allowing developers to effortlessly switch between different platforms and frameworks.
- JavaScript's widespread adoption and extensive community support provide developers with a vast array of resources, libraries, and frameworks, empowering them to build robust and scalable applications.
- JavaScript's dynamic nature allows for flexible and agile development, enabling developers to quickly iterate and adapt to changing requirements.
- Steep learning curve for team members unfamiliar with JavaScript, requiring additional time and effort for training.
- Limited debugging capabilities, potentially leading to longer troubleshooting and bug-fixing cycles.
- Lack of strong typing and compile-time checks may result in more runtime errors and potential issues.
- JavaScript's dynamic nature can make code maintenance and refactoring more challenging.
- Using other frontend technologies: This would not be fit for our project since it is possible that compatibility issues may arise due to JavaScript being the predominant frontend technology to date.
- Using other backend technologies: While PHP is still widely used as a backend technology in 2024, leveraging Node.js will undoubtedly reduce costs and development time by minimizing research and documentation tasks for the general-purpose developers within the team.
- Developing a desktop/local app instead of a web-based system: While this approach would eliminate the deployment complexities associated with web apps, a web-based system offers a more consistent user base due to the ease of access and the tools available in each client's web browser.
Creating a new microservice for the question generation service.
- The architectural design of the project is significantly improved, leading to better scalability, maintainability, and reusability.
- The new microservice allows for easier integration with other services and systems, promoting a modular and flexible application.
- By separating the question generation functionality into its own microservice, it becomes easier to scale and manage resources independently, ensuring optimal performance.
- The microservice architecture enables the team to adopt a microservices-based development approach, facilitating continuous integration and deployment.
- A new service will need to be created, implying additional work for the team. However, the long-term benefits outweigh the initial effort.
- Implementing the question generation functionality in an already existing service: This approach does not align with the project's requirements as there are no suitable alternatives where the new functionality can be seamlessly integrated without compromising the existing service's architecture and functionality.
- Utilizing a third-party question generation service: While this option may save development time, it introduces dependencies on external services and may limit customization and control over the question generation process.
- The QG microservice will be responsible for generating questions based on predefined rules and data, providing a scalable and efficient solution for the application's question generation needs.
- The microservice will try to follow industry best practices, such as using RESTful APIs for communication and implementing proper error handling and logging mechanisms.
- It will be developed using a suitable programming language and framework that aligns with the project's technology stack and the team's expertise.
- The microservice will be containerized using Docker, ensuring easy deployment and scalability.
- Integration tests and monitoring will be implemented to ensure the reliability and performance of the QG microservice.
Using Docker to deploy the application.
- Docker enables fast and effortless deployment, reducing the time and effort required for setting up the application environment.
- Docker containers provide isolation and consistency, ensuring that the application runs consistently across different environments.
- Docker simplifies scalability by allowing easy replication and distribution of containers.
- Docker's image-based approach promotes version control and reproducibility, making it easier to manage and roll back changes.
- Outdated or incomplete documentation may pose challenges when troubleshooting or seeking guidance.
- Docker introduces an additional layer of complexity, requiring developers to learn and understand containerization concepts and Docker-specific commands.
- Migrating from other virtualization technologies to Docker may involve a learning curve and potential complexities.
- Docker containers can consume significant disk space, especially when multiple containers are used.
- Using virtual machines (VMs): VMs provide similar benefits of isolation and portability, but they come with higher resource overhead and longer startup times compared to Docker containers.
- Using container orchestration platforms like Kubernetes: While Kubernetes offers advanced features for managing containerized applications, it adds complexity and requires additional infrastructure setup and maintenance.
- Using serverless platforms: Serverless platforms abstract away the infrastructure management entirely, but they may not be suitable for all types of applications and may introduce vendor lock-in.
Using React JS to create the user interfaces of the application.
- React's component-based architecture allows for granular updates of specific parts of a webpage, resulting in improved performance and user experience.
- React offers unparalleled versatility and extensive customization options, enabling developers to create visually stunning and interactive interfaces.
- Mastering React requires understanding complex concepts and advanced patterns, which may require additional learning and practice.
- React has a substantial library and dependency ecosystem, which may increase the initial setup and maintenance overhead.
- Using JavaScript natively: Opting for native JavaScript development would demand significant effort, time, and expertise, while also compromising the aesthetics and functionality of the frontend.
- Other JavaScript frameworks: Although there are alternative frameworks available, React's large and vibrant community support, coupled with its extensive ecosystem, make it the preferred choice for the project.
Using MongoDB as our primary database technology.
- MongoDB offers high performance and scalability, allowing for efficient handling of large amounts of data and high traffic loads.
- The flexible document-based model of MongoDB enables easy schema evolution and accommodates changing data requirements.
- MongoDB's built-in replication and sharding capabilities ensure high availability and fault tolerance for our application.
- Adopting a NoSQL database like MongoDB may require a learning curve for the team, as it introduces new concepts and practices compared to traditional relational databases.
- Complex joins and aggregations in MongoDB can be more challenging and less performant compared to relational databases.
- Using a relational database: While relational databases have a well-established ecosystem and are familiar to the team, they may not provide the same level of flexibility and scalability as MongoDB for our specific use case.
- Exploring other NoSQL databases: There are other NoSQL databases like Cassandra and CouchDB that offer different trade-offs in terms of scalability, consistency, and query capabilities. However, MongoDB's popularity, community support, and integration with our technology stack make it a strong choice for our project.
Using ExpressJS for the application's backend
- Lightweight and minimalistic framework
- Easy to learn and get started with
- Extensive middleware ecosystem for added functionality
- Excellent community support and documentation
- May require additional research and learning for the team
- Lack of strict structure or conventions for organizing code
- Not suitable for large-scale enterprise applications with complex requirements
- Koa: A modern and lightweight framework that offers a more streamlined and elegant API compared to ExpressJS.
- NestJS: A TypeScript-based framework that provides a structured and scalable approach to building backend applications.
- Fastify: A highly performant framework known for its speed and efficiency, suitable for building high-performance APIs.
Changing from Gitflow to Trunk Based Development
- Streamlined development process with a centralized codebase, reducing complexity and overhead associated with managing multiple long-lived branches.
- Faster feedback loop and quicker delivery of features and bug fixes, as changes are merged directly into the main branch.
- Encourages collaboration and knowledge sharing among team members, as everyone works on the same codebase.
- Simplifies release management and reduces the risk of merge conflicts.
- Requires a shift in mindset and practice to ensure proper synchronization and coordination among team members, as changes are merged directly into the main branch.
- May require additional tooling and automation to support continuous integration and deployment.
- Can be challenging to maintain stability and ensure the quality of the main branch, especially in larger teams or complex projects.
- Gitflow: A branching model that provides a structured approach for managing feature development and releases, suitable for projects with longer release cycles and strict versioning requirements.
- Feature Branching: A variation of Gitflow where each feature is developed in a separate branch, allowing for more isolation and parallel development, but potentially introducing more complexity and longer feedback loops.
- GitOps: A methodology that combines version control (Git) and infrastructure as code (IaC) practices to manage and automate the deployment and operation of applications, providing a declarative and auditable approach to software delivery.
Implementing SSL encryption for secure communication between the application and clients. The certificate will be generated with Let's encrypt.
- SSL encryption ensures the confidentiality and integrity of data transmitted over the network, protecting it from unauthorized access and tampering.
- SSL certificates provide authentication, allowing clients to verify the identity of the application server, mitigating the risk of man-in-the-middle attacks.
- SSL encryption is widely supported by modern web browsers and is a standard security practice for web applications.
- Implementing SSL encryption requires additional configuration and management of SSL certificates.
- SSL encryption can introduce a slight performance overhead due to the encryption and decryption processes.
- Since we are using the free subscription, the certificate will expire after 90 days, instead of 1 year (premium subscription).
- A domain name is required to register the certificate.
- An autogenerated certificate could be implemented but browsers will display an insecure messages, which is not desired.
Registering a domain name for the application. (open-domains/register#1042)
- A unique domain name enhances the brand identity and professionalism of the application.
- It improves user recall and credibility, making it easier for users to find and revisit the application.
- SEO benefits are significant, as having a dedicated domain improves search engine rankings and visibility.
- We can register the SSL certificate
- Periodic renewal for domain registration can be an ongoing cost.
- The desired domain name may not be available, requiring a compromise on the name or an increase in cost if purchasing from a current owner.
- Managing DNS settings and ensuring domain security requires technical knowledge and regular monitoring.
- Using a subdomain of a hosting provider: This can be a cost-effective solution but often lacks professionalism and can have limitations on SEO and branding.
- Utilizing new top-level domains (TLDs): Exploring less common TLDs might provide more name options, though they may be less recognizable to the general public.
Implementing a reverse proxy server for the application.
- Enhances security by obscuring the backend server details and providing an additional layer of protection against attacks.
- It could be used as a load balancer, which can distribute traffic across several servers, enhancing the application's scalability and reliability.
- Simplifies SSL termination, where the reverse proxy handles incoming HTTPS connections, decrypting requests and passing them as HTTP to the backend servers.
- Could facilitate static content caching, which reduces the load on the backend servers and improves response times for the users.
- Introduces an extra point of failure in the system architecture, which could lead to potential downtime if not managed properly.
- Adds complexity to the network configuration and maintenance, requiring specialized knowledge to implement and manage.
- May lead to increased latency if not configured correctly, especially in high-traffic environments.
- Direct server access: Removing the reverse proxy and allowing direct access to the server can simplify the architecture but reduces scalability and security.
- Cloud-based load balancers: These provide similar benefits but may introduce vendor lock-in and could be more expensive based on traffic volume.
Using the ELK Stack (Elasticsearch, Logstash, and Kibana) for logging and monitoring the application.
- Provides a powerful platform for searching, analyzing, and visualizing logs in real time, which is essential for troubleshooting and understanding application behavior.
- Enhances the ability to detect and respond to issues promptly, improving the overall reliability and performance of the application.
- Supports scalability, allowing the handling of large volumes of data efficiently.
- Facilitates compliance with regulations requiring log retention and analysis by providing robust tools for managing and retaining logs.
- The complexity of managing and configuring the stack can be high, particularly in large-scale deployments.
- Resource-intensive, requiring significant computing and storage resources, which could increase operational costs.
- The initial setup and learning curve can be steep for teams unfamiliar with the ELK Stack.
- Using managed logging and monitoring services: Services like AWS CloudWatch or Google Stackdriver offer managed solutions but can be expensive and less customizable.
- Simplified logging solutions: Tools like Splunk or Sumo Logic provide similar functionalities but might not offer the same level of flexibility or cost-effectiveness for large volumes of logs.
Using the deploy machine as a host for the heavier tasks in the autodeployment.
- It is a fun feature
- It makes our team waste fewer Github resources
- Quicker execution of the heavier tasks
- The self host could stop working if the machine is down, but since there is not point in deploying if the machine is down it does not constitute a big deal to the project.
- Using github free hosted runners, this is slow, limited and not fun.
- Using github enterprise plan runners, this is way to expensive for our goals.