AIMS Architectural Roadmap

Executive Summary 

This document outlines a software architectural roadmap for the AIMS product, focusing on addressing technical debt, enhancing scalability and performance, and improving security. The current architecture utilizes Angular v14 and .NET 6 with C# 10, with a deployment architecture including Azure services. The roadmap proposes key initiatives such as updating to Angular v15, removing deprecated libraries, implementing misdemeanor probation functionality, upgrading to .NET 8, and adopting a BFF security pattern. These changes aim to modernize the technology stack, improve system reliability, and ensure compliance with security standards. 

Current Architecture

Technology Stack 

Front-end

• Angular v14: UI framework developed by Google 

• Angular Material v14: Prebuilt UI Components developed for use in Angular 

• Sass CSS v1.58: Library used to style HTML elements 

• Authentication: 

  • OpenID Connect (OIDC): industry standard authentication protocol 

  • JSON Web Tokens (JWT): industry standard security token format 

  • oidc-client.js library: JavaScript library used to store user access tokens within the browser (deprecated 2/17/2021) 

Back-end  

• Microsoft .NET v6 with C# v10 

• Command Query Responsibility Segregation (CQRS): Separates the concerns of the Command (create, update, and delete) operations from the Query(read) operations 

• Dapper: An object relational mapping (ORM) library which simplifies the create, read, update, and delete (CRUD) operations on the database by automatically mapping database parameters and data results to C# objects 

• Fluent Validation: A library which allows developers to easily implement complex validation rules on all data sent to the API 

• MediatR: an in-memory bus which implements a publisher/subscriber (Pub/Sub) used to loosely couple the API layer to the Application Layer and handle intra-domain events 

• Azure Service Bus:  Robust message bus functionality used to communicate with external systems such as Ce Sync and for inter-domain events that must pass information between microservices  

• NodaTime: A date time management library used to extend the limited date time functionality provided by the .NET framework. Usage of frameworks such as this are key when implementing multi-tenant solutions as tenants and users are dispersed throughout the world and rarely in the same time zone as the servers 

• QuestPDF: This is a newly developed open-source library which is used to generate PDF documents using C# 

• Twilio: A communication library which enables the following functionality: 

  • Allows Clients to dial-in and interact with an automated voice system to conduct Pretrial Supervision Interviews 

  • Allows Clients to dial-in and be notified if they have been selected for random drug testing 

  • Provides functionality for AIMS to send SMS messages to Clients regarding Hearings, Drug Tests, Contacts or simply manual messages sent by their supervising officer 

• Authentication: 

  • OpenID Connect (OIDC) - industry standard authentication protocol 

  • JSON Web Tokens (JWT) - industry standard security token format 

  • Microsoft http://ASP.NET Core authentication libraries – latest encryption/decryption/verification libraries provided by Microsoft 

Database  

• Microsoft SQL Server 

Microsoft Word Interface

• Visual Studio Tools for Office (VSTO) 

Deployment Architecture  

When deployed, the application has the following Azure Footprint: 

Production

• 1 Azure App Service hosts all 3 services for 70+ tenants / 4000+ users: 

  • Front-end  

  • Back-end 

  • Word Installer 

• 1 Azure SQL Server 

  • 1 Master Database 

  • 70+ Tenant Databases 

• 1 Azure Blob Storage Account with 70+ Tenant Containers 

• 1 Azure Service Bus 

• 1 Step in Azure Deployment Process handles updating all 70+ databases (including master database) 

Non-Production

• 1 Click Deployment into 9 Test/Evaluation Environments

  • 6 Test Environments: Feature Acceptance / UI Approval

  • Prep Environment: Customer Go-Live Acceptance

  • Work-In-Progress Environment: Demos of future features

  • Preview: Release Candidate Testing

• 1 Click Replication of entire Production Environment (all tenant databases) into Preview Environment

• Releases are stored and can be deployed/redeployed into any environment

Assessment of system scalability, performance, and reliability 

• Scalability: The Azure App Service can be scaled in real time to handle increased workloads. 

• Application / Database Performance: The AIMS Production Deployment handles over 160 million requests per day with an average response time of 123 milliseconds. 

• Application Reliability: AIMS App Service can be deployed to different Azure Government Regions in case of an outage, however this is currently a manual process. 

• Database Reliability: AIMS database connection is part of failover group that will automatically change Azure Government Regions if a database in one region is detected. 

Identification of architectural bottlenecks and pain points 

• AIMS implements a very clean modern architecture with a clear separation of concerns between modules and layers within the application.  

• There is a steep learning curve when bringing new developers into this architecture. 

• Features oftentimes take longer to implement in AIMS because of the strict architecture. 

Evaluation of security posture 

• Authentication / Authorization: AIMS stores JWT Access Tokens client side in the browser. This method of storing tokens is now considered obsolete and the industry recommends switching to using a back-end for front-end (BFF) security architecture. 

• Back-End security: Each request to an API Endpoint must contain a User Access Token which is validated by the API layer before being processed by the Server. In addition to a valid User Access Token, the user’s account must have the proper permissions assigned within the AIMS system before being processed by the Server. 

• Sensitive Information: AIMS stores all sensitive information in an Azure Key Vault and accesses this information in an encrypted manner at runtime as necessary. 

Review of development and deployment processes 

Development

• Each development task is performed on a fork of the development branch 

• When a developer completes a feature, the feature is deployed to one of 6 test environments for testing and UI/UX approval 

• Only after successful testing and UI/UX approval is a PR created for the changes 

• A PR is created by the developer for review by senior team members 

• Only after approval of the PR is the feature merged back into the development branch 

• Testing is performed on the development branch 

• After testing has passed on the development branch, this branch is merged into the master branch for the next release 

Deployment

• A releasable version (frozen code) is created each time code is checked into the master branch. Releases can also be manually created and manually labeled with a version at any time. 

• An AIMS release can be deployed to 7 test environments, 1 preview environment, and the production environment with 1 click. 

• The preview environment can be updated to reflect the production environment with all the latest tenant databases with 1 click. 

• Production releases can be deployed multiple times to the preview environment to ensure compatibility with all tenant databases before the production environment is updated. 

Vision and Goals 

This section covers some issues in the AIMS system. The following items describe those issues and include steps to resolve the issues. 

Security 

As mentioned previously the User Access Tokens are stored in plain text client side. AIMS should be enhanced to implement the Duende Identity Server BFF Framework. 

Automated Testing

AIMS includes several automated tests for Angular using Jasmine/Karma and several automated NUnit/Moq tests for .NET code. The problem with these tests is as follows: the Jasmine/Karma tests simply test the Angular code while the NUnit/Moq simply test the .NET code. What was really needed was a testing implementation that would test the application end-to-end by logging in, loading a screen, updating/creating data, then verifying the results. Due to this need, several end-to-end tests were implemented using the modern testing tools Playwright and SpecFlow. These tools used together allow developers to describe tests that align with product requirements in a natural language. As the tests are run, detailed artifacts are created that can be examined to find portions of the application which are failing. While these Playwright/SpecFlow tests have been created, they were never merged into the AIMS build pipeline. 

Obsolete Technology

Most every tenant of the AIMS application makes use of the Microsoft Word Template Add-In. This functionality, which was built into Microsoft Word, allows a user to create a document template with placeholders for data from the database. When a user chooses to use one of these templates, the templates are rendered on the Server and appear on the Client’s Documents Tab. The user can then download these documents and modify them as necessary then update them within the application. The issue is that many of the libraries used with Visual Studio Tools for Office (VSTO) to create this Add-In are now obsolete. This functionality should most likely be ported in the future to work with Office 365. 

Architectural Principles 

Following are industry established architectural principles to be followed when designing new functionality for the application:  

• Modularity: Compose discrete, interchangeable modules with well-defined interfaces, promoting reusability, maintainability, and ease of understanding. 

• Scalability: Architect features to scale horizontally and vertically to accommodate growing user bases and increased workloads, leveraging distributed systems and efficient resource utilization. 

• Loose Coupling: Minimize dependencies between components to reduce the impact of changes and facilitate independent development, testing, and deployment of modules. 

• High Cohesion: Ensure that each module or component has a clear, focused purpose and functionality, promoting better maintainability, testability, and understanding of the codebase. 

• Separation of Concerns: Divide the application into distinct layers or components, each responsible for a specific aspect of functionality (e.g., presentation, business logic, data access), to improve modifiability and clarity of design. 

• Security by Design: Integrate security measures and best practices into the architecture from the outset, including authentication, authorization, encryption, and secure communication protocols, to protect against potential threats and vulnerabilities. 

• Performance Optimization: Architect the application to be performant by employing efficient algorithms, data structures, caching mechanisms, and optimization techniques to minimize latency, maximize throughput, and optimize resource utilization. 

• Flexibility and Extensibility: Design the application to accommodate future changes and enhancements by adopting flexible, extensible architectures and design patterns that allow for easy integration of new features, modules, and technologies. 

• Resilience and Fault Tolerance: Build the application to withstand and recover gracefully from failures, errors, and unexpected events by implementing fault-tolerant mechanisms, redundancy, graceful degradation, and automated recovery processes. 

• Testability: Ensure that the application is designed for ease of testing, with clear separation of concerns, modular architecture, and support for automated testing frameworks and tools to facilitate comprehensive testing and validation of functionality. 

• Simplicity and Minimalism: Strive for simplicity in design and implementation, favoring straightforward solutions over overly complex ones, to reduce cognitive overhead, minimize technical debt, and improve maintainability. 

• Adaptability to Change: Architect the application to be adaptable and responsive to changing business requirements, technological advancements, and user feedback, enabling iterative development, continuous integration, and delivery practices. 

Key Initiatives 

This section describes major architectural initiatives planned to minimize technical debt and address the shortcomings defined in the vision and goals section of the document. 

Initiative 1: Update Front-end Framework 

• Description:  AIMS is currently running Angular v14 in Production which has been out of Active Support since 11/18/2022 and out of Security Support since 11/18/2023.  

• Objective:  Update to Angular v15 which provided Active Support through 5/3/2024 but does provide Security Support through 11/8/2024. 

• Timeline:  To be finished by the end of Q2 2024. 

• Key Milestones:  

  • Start of Q2 2024: Development branch upgraded to Angular v15 

  • Mid Q2 2024: Update Preview branch with latest customer data to Angular v15 

  • Mid Q2 2024: Verify all customer implementations function correctly with Angular v15 

  • End of Q2 2024: Incorporate any issues found into ongoing sprint work 

  • End of Q2 2024: Update Production branch to Angular v15   

Initiative 2: Remove deprecated Angular Flex-Layout library 

• Description:  A deprecated Angular library “Flex-Layout” must be removed from the solution in order to move past Angular v15.  If this library is not removed and replaced before November 2024, AIMS will be running an Angular version in Production that is out of Security Support. 

• Objective:  Remove or replace the Flex-Layout with like functionality. The Angular team recommends moving to CSS Flexbox and CSS Grid. 

• Timeline: To be worked on between Q1 2024 and Q3 2024. 

• Key Milestones: 

  • Q1 2024: Identity a complex UI screen within AIMS and rewrite it using CSS Flexbox and CSS Grid technologies 

  • Mid Q2 2024: Demonstrate and explain the rewrite during a presentation to the development team 

  • Q3 2024: Incorporate the redesign of all existing screens using Flex-Layout into ongoing sprint work 

Initiative 3: Misdemeanor Probation in AIMS 

• Description: To decrease reliance on our older Probation Management application we are building out Probation functionality in the AIMS product.   

• Objective: Implement core probation functionality into the AIMS application. 

• Timeline: To be worked on between Q1 2024 and ≈ Q4 2025. 

• Key Milestones:  

  • Q1 2024-Q2 2024: Replicate core AIMS functionality into the Probation module including Accounting, Assessments, Contacts, Documents, Drug Testing, Messaging, etc. 

  • Q3 2024: Recruit smaller Probation agencies to review the application and provide feedback 

  • Q4 2024-Q4 2025: Incorporate agency feedback into ongoing sprint work 

Initiative 4: Update Back-end Framework 

• Description: The back-end of AIMS is currently .NET 6 / C# 10. Active Support for this LTS version of the framework ends 11/12/2024. Given that support for version 7, which is a short term support version of the .NET framework ends 5/14/2024, we should target moving to .NET 8 LTS which will be supported through 11/10/2026.  

• Objective: To upgrade our backend to .NET 8 / C# 12.  

• Timeline: To be finished by the end of Q2 2024. 

• Key Milestones: 

  • Start of Q2 2024: Update all 78 projects in AIMS to .NET 8 / C# 12  

  • Mid Q2 2024: Identity features that are no longer supported in .NET 8 or that can be enhanced using the new language features of C# 12 

  • End of Q2 2024: Incorporate deprecated features / C# enhancements into ongoing sprint work 

Initiative 5: BFF Security Implementation 

• Description: AIMS is currently utilizing JavaScript technologies to store security tokens in plain text on the client computer which is insecure. 

• Objective: Implement a back-end for front-end (BFF) security pattern which removes the security tokens from the client computer and implements encrypted cookies which can only be decrypted by the server. 

• Timeline: To be finished by the end of Q3 2024. 

• Key Milestones: 

  • Start of Q3 2024: A branch has already been created with BFF technology incorporated 

  • Mid Q3 2024: Enhance existing Azure pipelines to deploy this solution to an Azure environment 

  • Mid Q3 2024: Evaluate the functionality of this environment against all existing third-party agency interfaces 

  • Mid Q3 2024: Identity any third-party interfaces which rely on less secure authentication methods 

  • End of Q3 2024: Incorporate security enhancements into ongoing sprint work 

Dependencies and Risks 

Identification of dependencies between architectural initiatives and potential risks (e.g., resource constraints, technology adoption challenges) that could impact successful implementation. 

• Angular Flex-Layout will affect a large percentage of the approximately 800 HTML files in AIMS 

• Updating unsecure JavaScript authentication to BFF may have an impact on older, less secure, third party interfaces which have not been worked on for several years 

Resource Allocation 

1. Update Front-end Framework 

   1. Resource Allocation:  Sammie, Mohammed, Gabe, Audrius 

   2. Training Needs: None 

2. Remove deprecated Angular Flex-Layout library 

   1. Resource Allocation:  Sammie, Mohammed, Gabe, Audrius 

   2. Training Needs: Review training on Angular’s Flexbox model 

3. Misdemeanor Probation in AIMS 

   1. Resource Allocation:  Entire Automon team + Bradey 

   2. Training Needs:  

      1. Review available documentation on new involvement types

      2. Improve documentation while in progress 

4. Update Back-end Framework 

   1. Resource Allocation:  Entire Automon team 

   2. Training Needs: Review .NET and C# upgrade documentation

5. BFF Security Implementation 

   1. Resource Allocation:  Entire Automon team 

   2. Training Needs:  

      1. Re-train with Bradey 

      2. Cross-discussions with Jury V2 team on impediments 

Governance and Oversight 

 Purpose 

This plan establishes a clear framework for software development and architecture governance within the Jury V2 project. This framework will guide the design, development, and maintenance of our systems, ensuring consistency, quality, and alignment with our business objectives. 

Scope 

This plan covers all aspects of software development and architecture for the Jury V2 product, including design principles, development processes, architectural standards, and governance mechanisms. 

Architecture Vision 

Strategic Goals 

• Enhance user experience and accessibility. 

• Ensure scalability and performance. 

• Maintain security and compliance standards. 

• Facilitate integration with external systems. 

Key Principles 

• Modularity: Design systems as a collection of independent, interchangeable modules. 

• Interoperability: Ensure systems can exchange and use information seamlessly. 

• Scalability: Design systems to handle increasing loads gracefully. 

• Security: Embed security considerations into every aspect of the architecture. 

Development Process 

Agile Methodology 

• Sprints: Develop features in short, iterative cycles (sprints).  Sprints will last 2 weeks. 

• Backlog Management: Maintain a prioritized list of user stories and tasks. 

• Continuous Integration/Continuous Deployment (CI/CD): Automate testing and deployment processes. 

Quality Assurance 

• Code Reviews: Conduct regular code reviews to ensure code quality and adherence to standards. 

• Automated Testing: Implement a comprehensive suite of automated tests (unit, integration, and end-to-end). 

• Performance Monitoring: Continuously monitor system performance and address any issues proactively. 

Architecture Governance 

Architecture Review Board (ARB) 

Establish an ARB comprising key stakeholders to oversee architectural decisions. The ARB will: 

• Review and approve architectural designs and changes. 

• Ensure alignment with strategic goals and compliance with standards. 

• Resolve architectural conflicts and issues. 

Standards and Guidelines 

Develop and maintain a set of architectural standards and guidelines, covering: 

• Coding standards 

• Security protocols 

• Data management practices 

• Integration patterns 

Compliance and Auditing 

Implement mechanisms to ensure compliance with architectural standards and guidelines, including: 

• Regular audits of code and architecture 

• Automated tools to enforce standards 

• Reporting and addressing non-compliance issues 

Communication Plan 

Meetings 

Architecture Project Kick-off Meeting: 

Frequency: At the project initiation phase. 

Attendees: All stakeholders. 

Purpose: Introduce the project, its goals, roles, and expectations. 

Bi-Weekly Status Meetings: 

Frequency: Every other [Specify Day] at [Specify Time]. 

Attendees: Software Development. 

Purpose: Discuss progress, address issues, and plan for the upcoming sprint.  Decide if changes are needed to architectural plan. 

Sprint Planning Meetings: 

Frequency: At the beginning of each sprint. 

Attendees: Software Development, Product Management, and Project Management teams. 

Purpose: Define sprint goals, prioritize tasks, and align on the scope. 

Sprint Review/Demo Meetings: 

Frequency: Every other [Specify Day] at [Specify Time]. 

Attendees: Software Development, Implementation, Product Management, and Project Management teams. 

Purpose: Demonstrate work that has been completed, discuss sprint goals and what was completed.  Architecture work will be part of normal sprint demo time. 

Communication Tools 

Roles and Responsibilities 

Escalation Process 

In case of unresolved issues or conflicts, the following escalation process will be followed: 

Reporting 

Regular status reports will be shared with all stakeholders, summarizing progress, issues, and action items. These reports will be distributed after each bi-weekly status meeting. 

Metrics and KPIs 

Scalability: Measure the system's ability to handle increased workload or growth in data volume, users, or transactions. 

Reliability: Evaluate the system's ability to perform consistently and predictably under varying conditions. 

Maintainability: Assess how easily the system can be maintained, updated, and enhanced over time. 

Interoperability: Evaluate the system's ability to work seamlessly with other systems or components. 

Compliance: Ensure that the system meets regulatory, legal, and contractual requirements. Also ensure the security ticket backlog is regularly mitigated. 

Review and Update Process 

To ensure that the architectural roadmap of the Jury V2 product is regularly reviewed and updated to align with evolving business needs, incorporate emerging technologies, and address feedback from stakeholders. 

1. Initiation: The review and update process is initiated quarterly, triggered by the end of each quarter. 

2. Stakeholder Identification: Identify key stakeholders who will contribute to the review and update process, including product managers, implementation personnel, developers, QA, architects, and any other relevant parties. 

3. Feedback Collection: 

   1. Stakeholders provide feedback on the current architectural roadmap, highlighting areas for improvement, emerging trends, and business needs. 

   2. Feedback can be collected through surveys, interviews, and workshops. 

4. Review Meeting: 

   1. A review meeting is scheduled with key stakeholders to discuss the feedback and assess the current architectural roadmap. 

   2. The meeting agenda includes a review of the feedback, identification of key areas for update, and prioritization of changes. 

5. Update Proposal: 

   1. Based on the review meeting, a proposal is drafted to update the architectural roadmap. 

   2. The proposal includes a summary of feedback, proposed changes to the roadmap, rationale for the changes, and estimated impact on the product. 

6. Approval Process: 

   1. The update proposal is presented to the ARB and development management for approval. 

   2. The ARB and development management team evaluates the proposal based on alignment with business goals, feasibility, and resource availability. 

7. Implementation Planning: 

   1. Once approved, an implementation plan is developed detailing the steps, timeline, and resources required to implement the updates. 

   2. The plan includes the previous communication plan to inform stakeholders about the upcoming changes. 

8. Implementation: 

   1. The updates to the architectural roadmap are implemented according to the plan. 

   2. Developers and architects collaborate to ensure that the updates are integrated smoothly into the development process. 

9. Monitoring and Feedback: 

   1. Post-implementation, the updated roadmap is monitored closely to assess its impact on the product. 

   2. Feedback is collected from stakeholders to evaluate the effectiveness of the updates and identify any further improvements needed. 

10. Documentation: 

    1. All updates to the architectural roadmap, including feedback, proposals, and implementation plans, are documented for future reference. 

    2. Documentation is made accessible to stakeholders for transparency and accountability. 

11. Continuous Improvement: 

    1. The review and update process is iterative, with regular reviews scheduled to ensure that the architectural roadmap remains aligned with business needs and technology trends. 

    2. Lessons learned from each review cycle are used to improve the process for future updates. 

Conclusion

The review and update process outlined above ensures that the architectural roadmap of the product is regularly reviewed and updated to meet the evolving needs of the business, incorporate new technologies, and address feedback from stakeholders. This process helps to ensure that the product remains competitive, innovative, and aligned with the strategic goals of the organization.