how to create application design document

Project Name :........

Project Id :........

Version: .........

Date :.........

1.. Introduction

2.. Approach

2.1.... Methodology Approach

2.2.... Key Design Principles

2.3.... Conventions and Standards Followed

2.4.... Common Rules and Routines

3.. System Assumptions and Dependencies

4.. System Description

4.1.... Technical Environment

4.2.... System Design/Flow Charts

5.. Database Design

5.1.... Key Design Principles

5.2.... Data Model

5.2.1.        Data Model Overview

5.2.2.        Table Details

5.2.3.        Database Programming

5.2.4.        Access Control Details

6.. Functional Requirements

6.1.... Functional Design Catalogue

6.2.... Design Detail

6.2.1.        <Program Name # 1>

6.2.2.        <Program Name # 2>

6.3.... Exception Handling

7.. Report Requirements

7.1.... Report Catalogue

7.1.1.        Report Layouts

8.. System Interface Requirements

8.1.... Interface Catalogue

8.2.... Interface Detail

8.2.1.        <Interface # 1>

8.2.2.        <Interface # 2>

9.. Non-Functional Requirements

9.1.... Non-Functional Requirements catalogue

9.1.1.        System Availability Requirements

9.1.2.        Scalability Requirements

9.1.3.        Security Requirements

9.1.4.        Data Management Requirements

9.1.5.        Performance Requirements

9.1.6.        User Look and Feel Requirements

9.1.7.        Supportability Requirements

9.1.8.        Maintainability Requirements

9.1.9.        SLA Requirements

10. Business Continuity / Disaster Recovery

11.Decommissioning of the old functions/systems

12. Appendix

12.1.. Acronyms and Abbreviations

12.2.. Key Design Principles

12.3.       Design Patterns

1.Introduction

1. Note: This document is intended to contain detailed descriptions about exactly how to build the functional requirements targeted at developers, and testers. Functional designs are captured in Functional Design Document. This document aims to ‘translate’ the Functional Design Document into more technical detail design.
   The overall DDD is a detailed design that is the basis for all application specific DDD's. The goal of the overall DDD is to provide specific frameworks and other information for individual application detail design.

2.Approach

2.1.Methodology Approach

This section describes the methodology and process used to develop the design.

In order to develop the overall detail design, information was gathered from static code analysis, migration analysis and other tooling. Utilizing this information, application industry and bank direction (security, containerization, decoupling, MVC), directives from Enterprise Architecture, and discussions with various teams, the overall DDD was produced.

It is important to note that all tooling results will be provided for teams when they create their DDD

2.2.Key Design Principles

The key principles driving this design are:

·        Decoupling

·        Services First

·        Shared Services and Components

·        Canonical Model for Services

·        Standardized Libraries

·        Test Automation

These principles are important to ensure reusability, scalability, and reduce risk

2.3.Conventions and Standards Followed

Please provide a list of all conventions and standards that will be followed in the design of the application, this can include Special Naming conventions, file naming conventions, etc. This section can also include security standard followed

Applications will use the following application frameworks as part of the design:

Framework	Purpose
Spring 5.0.x	Application framework that is used to increase modularity and reusability through usage of interfaces.
Spring MVC 5.0.x	Web application framework implementing the MVC design pattern
JPA -> Hibernate 5.x	Framework for mapping domain models to a database.  The framework helps to minimize usage of dynamic SQL leading to most SQL Injection attacks.

Should we have hibernate here?  Need to make sure it’s fronted with JPA

Applications will only use libraries (vendor specific) available from the internal Nexus Repository as part of the design.  If a library is not available, a request will have to be submitted.

2.4.Common Rules and Routines

This section contains the rules and routines that are common to all (or most) program applications in the system and the software infrastructure standards (incl use of common/ shared areas)

Application will be decoupled according to the following reference design.

Layer	Description	Deployment Tier
Presentation	Client side user interface of the application	Web Tier
Application	Server side components of an application ·         MVC Controller ·         REST/SOAP Provider ·         JMS Consumer	Web Tier Service Tier
Domain	Business logic components of an application	Service Tier
Infrastructure	Physical infrastructures an application uses	N/A

Cross cutting features (i.e. security, logging, caching, etc.) will provide interfaces that are shared across all applicable layers.

The overall DDD will provide specific guidance and directives to solve common application design problems including:

• 1      Security
• 2      Caching
• 3      Integration

The overall DDD will specify processes for:

• 1      Application Packaging
• 2      Application Deployment
• 3     Externalization and Vaulting of Resources
• 4    Service Registration
• 5    Monitoring and Alerting
• 6     A/B Deployment Model

3.System Assumptions and Dependencies

This sub-section shall list all the assumptions and dependencies taken into account while preparing the Detailed Design document. Such assumptions are not outstanding issues; rather they are valid assumptions on which the design is based

4.  System Description

This section provides the description of technical environment and system design and the supporting flow charts (sequence diagrams, use cases, etc.)

The overall DDD will describe application deployment environments, interactions between environments, shared services and systems.

The overall DDD will not describe application specific business logic. The business logic should follow the aforementioned key design principles.

4.1.Technical Environment

This section defines the facilities, standards or design restrictions for the particular technical environment. This includes client and server configurations, network topology, systems software, development tools and gateways. In addition, this section describes any additional resources required for the application such as disk, memory, database etc.

The technical environment implements the n-tiered architecture.  Each of the tiers is isolated into separate network security groups (NSG) and can scale independently of each other.

Execution Environment

Web Tier

RedHat EWS (Apache) or RedHat JWS (Tomcat)

Service Tier

JBoss EAP or JBoss Fuse

Data Tier

Oracle

Cache Tier

JBoss DataGrid

N/A

Akana API Gateway

Development Desktop Environment

Developers will have the following tooling available:

·         Java 11

·         Maven 3.5.x[A1] 

·         Git Client

·         MKS Client (For migration to BitBucket support)

·         JBoss EAP 7.2.x

·         RedHat JBoss Web Server 5.x (Tomcat 9)

·         RedHat EWS (Apache)

·         JBoss Fuse 7.x

·         Eclipse / JBoss Developer Studio

For containerize build and deployment locally:

·         Windows 10

·         Docker

·         MiniShift

·         HyperV[A2] 

Packaging

Applications will use Maven as the build tool to package and build deployment artifacts supporting the deployment model.

Deployment Artifact	Description
ApplicationUI.war	Web Archive containing presentation and application layer
Application Business Logic.ear	Enterprise Archive implementing application and domain layer containing business logic for application
Application Service Orchestration.fab	Fuse fabric 8 archive implementing business logic orchestrating multiple external services.
Application Schema	Database DDL for tables, functions, procedures, etc.
Service Registration	Services API exposed for external applications to consume.

Enterprise POM and Bill of Materials

Applications will use only the libraries defined in the Bill of Materials (BOM) defined in the Enterprise POM.  Do not override the scope of the libraries in the Enterprise POM.  Provided libraries are deployed as shared libraries in the execution environment (i.e. JBoss Modules) and should not be part of the application packaging.

Libraries not in the Enterprise POM will have to be approved through a request

Source Code Management

BitBucket will be used to store all application source code.  Applications that are not currently using BitBucket (i.e. MKS) will need to migrate to BitBucket.

Continuous Integration and Builds

Applications will use Jenkins for continuous integration (CI) and release builds and promotions.  Only builds from the automated build environments can be promoted to Test, UAT, and Production.

Application Lifecycle Management

The following Application Lifecycle Management Tools will be used.

Purpose	Tools
Requirement Management	JIRA + Confluence
Test & Quality Management	HPQC
Issue & Defect Management	JIRA + Confluence
Build & Release Management	Jenkins + Puppet
Library Management	Nexus
Source Management	BitBucket
Static Code Analysis	SonarQube
Security Analysis	OWASP, VeraCode, Twistlock

4.2 System Design/Flow Charts

This section provides the description and system design and the supporting flow charts (sequence diagrams, use cases, etc.)

5. Database Design

This section contains the record descriptions and describes how they are transformed into physical databases/ files and record descriptions. This section contains a sub-section for each of the databases/ files processed by the system containing the detailed database/file, record and data item specifications. The results of database/ file design should be recorded in an automated Data Dictionary, which can be accessed directly by language compilers, database systems, etc. and held independent of programs which access the records

5.1.                      Key Design Principles

·        Do not deeply nest tables

·        Do not try to migrate from existing DB unless it is critical

·        Do not use common lookup tables

5.2.                      Data Model

5.2.1.               Data Model Overview

Depict the Data model diagram, if applicable

5.2.2.               Table Details

Provide a tabular format, which captures the following details. While deriving tables from the object model, the different associations will need to be considered separately.

5.2.3.               Database Programming

Identify stored procedures that will access these tables and the operations that this will perform. Also list out any triggers or views that has been created/modified as part of the implementation

5.2.4.               Access Control Details

·        Details that are not specific to any program of the application, but connected to database /file system.

·        Administration

·        Security and access rights (DB Role and Users)

Record locking, etc.

6.  Functional Requirements

The overall DDD does NOT include specific business functionality that defines what a system will accomplish. This should be done in the applications’ DDD.

If the application has the following requirements, refer to the documented NFR solution:

Requirement	NFR
Authenticates with username and password	Authentication and Authorization Scalability Requirements Data Cache
Provides role based security	Authentication and Authorization
Orchestrates Business logic between two or more external services	Integration Service

6.1.   Functional Design Catalogue

This section is a placeholder for the excel template (embed in the Business Requirements word document-section 4.1) used to catalogue the set of components that need to be designed and built. This template should be created once the Functional Design has been completed and signed-off.

6.2.  Design Detail

This section contains the detailed specifications for each program or application in the system/package. Each program should have a separate section heading in the document with the following table populated.

6.2.1.   <Program Name # 1>

Functional requirements – DDD
Component	Description
Program Name
Description	·
Flow Chart
Entry Conditions	·
Exit Criteria	·
Processing Logic	·
Error/Recovery Routines	·

6.2.2.   <Program Name # 2>

Functional requirements – DDD
Component	Description
Program Name
Description	·
Flow Chart
Entry Conditions	·
Exit Criteria	·
Processing Logic	·
Error/Recovery Routines	·

6.3.   Exception Handling

This section describes the exception handling measures on the system. If this is not covered explicitly in the design requirements excel, make sure to include the same here. Else this section can be N/A

7.1. Report Catalogue

This section is a placeholder for the excel template (embed in the Functional Requirements word document-section 10.1) used to catalogue the set of interfaces that need to be designed and built. This template should be created once the Functional Requirements document has been completed and signed-off.

7.1.1. Report Layouts This 

8. System Interface Requirements

The overall DDD will provide specific service APIs for key services (i.e. HTML Sanitizer Service).  Standard vendor API's will be provided by linking to the vender documentation.

If the application has the following requirements, refer to the documented NFR solution:

Requirement	NFR
Exposes Services to other Apps	Service Registration
Uses External HTML	HTML Sanitizer Service
Accepts Input from Users	Input Validation Service
Accepts Input from Service Endpoints	Input Validation Service
Stores Passwords in Configuration Files	Externalization and Vaulting of Resources
Establishes Database Connections	Database Connections
Establishes MQ Connections	MQ connections

8.1.Interface Catalog

This section is a placeholder for the excel template (embed in the Functional Requirements word document-section 10.1) used to catalogue the set of interfaces that need to be designed and built. This template should be created once the Functional Requirements document has been completed and signed-off.

8.2.Interface Detail

This section contains the detailed specifications for each system interface that needs to be designed and built. Each interface should have a separate section heading in the document with the following set of tables populated.

8.2.1.   <Interface # 1>

Message format table
File Image	File Attached
<Event # 1> :
<Event # 2> :

Processing requirements table
Solution Component	Solution Description
Data Encryption/Decryption	·
Authentication	·
Key Handling	·

Sequence management table
Solution Component	Solution Description
Sequence Detection	·
Process for handling out of sequence messages	·

8.2.2.   <Interface # 2>

Message format table
File Image	File Attached
<Event # 1> :
<Event # 2> :

Processing requirements table
Solution Component	Solution Description
Data Encryption/Decryption	·
Authentication	·
Key Handling	·

Sequence management table
Solution Component	Solution Description
Sequence Detection	·
Process for handling out of sequence messages	·

9. Non-Functional Requirements

If the application has the following requirements, refer to the documented NFR solution:

Requirement	NFR
Database Caching of Queries (L1) and Entities (L2)	Data Cache
Application Data Caching	Data Cache

9.1.Non-Functional Requirements catalogue

This section is a placeholder for the excel template (embedded in the Business Requirements Word document-section 4.2) used to catalogue the set of Non-Functional requirements that need to be designed and built. This template should be created once the Functional Design has been completed and signed-off.

The overall DDD will provide design solutions to meet standard requirements. They are:

1.     Security

2.     Scalability

3.     Monitoring and Alerting

The overall DDD will not provide information that would require changes to the base application such as user look at feel.  In cases in which a technology has been sunset and new technology has taken its place (i.e. Struts->Spring MVC), links to migration guidance may be provided.

9.1.1. System Availability Requirements

This section contains the descriptions how to implement the system availability requirements.

The overall DDD will provide design solutions based on applications’ system availability requirements (i.e. Circuit Breakers).

9.1.2.  Scalability Requirements

This section contains the descriptions how to implement the scalability requirements.

The n-tiered architecture states that each tier should be stateless and can scale independently from each other.

Stateful applications

A distribute cache (Data Cache) solution is provided for http sessions, application data and database cache.  Applications utilizing the distribute cache can have traffic route to any node as the tier is scaled up or down.

Shared File Systems

For transactional files, a common storage will be made available and shared between nodes on the same tier.  Any node will be able to fulfil the steps to complete an application transaction.  NFS mounts will be made for non-containers, and persistent volumes back by NFS mounts for containers.

9.1.3.Security Requirements

This section contains the descriptions how to implement security requirements

9.1.3.1.  Common Security Services

Service	URL	Description
HTML Sanitizer Service		Sanitizes untrusted HTML to protect against cross-site scripting (XSS).
Input Validation Service		Common input validators (syntactic and/or sematic) that will protect against injection attacks.

HTML Sanitizer Service

Including untrusted HTML content external to the application opens the application up to Cross Site Scripting attacks.  The HTML Sanitizer service will act as proxy service to remove any malicious content so the content can be safely included in the application.

Interface Exposed – <TBD>

Implementation - <TBD>

Input Validation Service

Injection attacks are the most common form of attack and currently on the top of the OWASP top 10.  One way to prevent injection attacks is to validate all inputs both on the client and on the server.  In order to have consistent validation (whitelist and blacklist), applications will use these validations on the presentation layer, application layer, and domain layer.

Validator	Whitelist Rule	Blacklist Rule
SSN
Email
Address
Credit Card Number

Presentation Layer Validation

<tbd: sequence diagram>

<tbd: sample code>

Application and Domain Layer Validation

<tbd: sequence diagram>

<tbd: sample code>

9.1.3.2 Authentication and Authorization

<TBD SiteMinder and LDAP>

9.1.3.3 Externalization and Vaulting of Resources

Passwords and Secrets cannot be stored as clear text.  Secrets and passwords needs to be stored externally and a reference security token stored in the configuration files.

9.1.4.Data Management Requirements

This section contains the descriptions how to implement the data management requirements

9.1.5. Performance Requirements

This section contains the descriptions how to implement the performance requirements

9.1.5.1. Data Cache

Data caching will be used to help solve common issues with high availability, network latency, database latency, etc. 

JBoss DataGrid is selected as the caching solution.  Applications can use the solution locally (library mode) and/or distributed (client-server).

Local Cache should only be used for:

·        Application has only one server for each tier and has no plans to scale horizontally.

·        Cache Data is specific to only the server (i.e. server name, IP, path, etc.)

·        Data is not shared with other servers

Distribute Cache should be used for:

·        Applications running in containers

·        Applications with two more nodes per tier

·        Application tiers are stateless and needs state management (i.e. HTTP session)

·        Data is shared with other servers

Type of Cache	Solution
HTTP Session
Application Data	Use JCache over JBoss DataGrid.
Entity/Query Cache	Level 1 and Level 2 over JDataGrid configuratio

9.1.6. User Look and Feel Requirements

This section contains the descriptions how to implement the user look and feel requirements

For the overall DDD this section is N/A.

9.1.7. Supportability Requirements

This section contains the descriptions how to implement the supportability requirements

9.1.7.1.API Gateway

To continually upgrade and fix security vulnerabilities without impacting or being burden by existing upstream and downstream applications, all application exposed services should be registered through the Akana API gateway. 

This will allow applications to be:

·        Loosely decoupled allowing an application to upgraded independently of each other.

·        Utilize the A/B deployment to upgraded APIs.

<add link to documentation of service registration>

9.1.7.2.Integration Service

Orchestration and transformation of data amongst two more external services can be challenging.  With the use of JBoss Fuse as an Integration Service, existing building blocks can be used to simplify the design.

JBoss Fuse provides:

·        Routing

·        Transforming

·        Exception Handling (i.e. Circuit Breaker)

Additional details about JBoss Fuse:

https://access.redhat.com/documentation/en-us/red_hat_fuse/7.0/html/apache_camel_development_guide/

9.1.8.Maintainability Requirements

This section contains the descriptions how to implement the maintainability requirements

To support the upgrading of supporting infrastructure (i.e. Database, MQ, etc.), applications will not package or include vendor specific drivers in the application.  Access to these infrastructures should be through resource adapters.

9.1.8.  Database Connections

Connections to databases will be established through JNDI datasource lookup.

https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.0/html/configuration_guide/datasource_management

9.1.8.2.MQ connections

Connections to MQ will be established through JNDI resource adapter lookup.

https://access.redhat.com/documentation/en-us/jboss_enterprise_application_platform/6.3/html/administration_and_configuration_guide/deploy_the_websphere_mq_resource_adapter

9.1.9      SLA Requirements

This section contains the descriptions how to implement SLA requirements

10   Business Continuity / Disaster Recovery

This section should specify the backup and recovery / disaster recovery capabilities of the system including archive facilities.  Please also specify what happens if the system is unavailable for a period of time:

·        Types of failure, and action to be taken in each instance.

·        Features not available / reports not produced under contingency mode of operation.

·        Manual procedures for prolonged machine failure.

·        For containers only, the overall DDD will provide a link to any EIS guidance on this topic.

11.  Decommissioning of the old functions/systems

This section should describe the tasks required to phase out the existing function (Tidal process etc.) or system.

A high level process for application migration to minimize upstream and downstream impact of change will be provided.  In addition, a process to roll forward/roll back an updated application with a focus on A/B testing will be provided. The overall DDD will also specific a process for retirement of non-longer used interfaces for cases in which an older (non-supported) interface was required.

12.      Appendix

12.1.  Acronyms and Abbreviations

12.2 Key Design Principles

·        Decoupling

https://www.tutorialspoint.com/software_architecture_design/key_principles.htm

·        Services First :

https://medium.com/adobetech/three-principles-of-api-first-design-fa6666d9f694

·        Canonical Model for Services

https://www.enterpriseintegrationpatterns.com/patterns/messaging/CanonicalDataModel.html

·        Test Automation

https://smartbear.com/learn/automated-testing/

12.3.      Design Patterns

·        N-Tiered (3+ Tier)

·         Model-View-Controller

DDD Template Revision History