Real Estate Management system (REM) - lin-o-a/REM-architectureSolution Wiki

User story

The client wants to account for buildings information incl. landlords and tenants. The tenants pay rent for living there(should be accounted for). A building can be repaired or improved by utility or facility services(any information should be accounted for).

💎Click to show/hide comments

Comment 1: if a tenant(not a landlord) pays for it, then the sum is included in his/her rent payment.

Comment 2: in property management, a building is called an object, thus in a system should be this term.

Comment 3: property manager has a right to see all tenants' rent payments, but tenants have not.

Comment 4: facility service we do not account for now, but considering for the future.

Functional requirements

Let`s extract requirements from the User story

  1. To have an ability to account of objects(buildings), landlords, tenants
  2. To have an ability to account of object issues(e.g. repairings, improvements)
  3. To have an ability to account (including calculations) of object payments

Description of processes

Process list

Let's extract processes from the requirements

  • to account buildings/landlords/tenants
  • to repair/modernize something in buildings
  • to account payments.

Package diagram

Let's describe packages across which are spread the processes:

  1. Account management package involves an account of buildings, landlords and tenants incl. rental documents management
  2. Maintenance management package involves building(s) repairing, modernization and related activities as issue management
  3. Transaction management package involves building(s) payment calculation and documentation
💎Click to show/hide comments

Comment 0. Package = System = C# Solution.

Comment 1. System is a logical unit that combine its subsystems by an idea considering a domain logic.

Comment 2. This is a diagram of REM and related systems:

Comment 3. What's the aim of such division? Every developer works only with 1 and several related services at a time and do not need to store all the project every time.

Comment 4. Sub-systems of the system are independent and do not communicate with each other, thus developers work in parallel and do not disturb each other.

Let's show the package structure in a diagram (made considering General system and graph theories)

In a diagram, except for packages with real estate domain logic(Facility, Property, Account Management packages) there are some with technical domain logic:

e.g. File Data Management that is used to convert file documents from/to different extensions or manage their storing(e.g. database) configurations; Core Management that consists of Code Management package(dependency injection mechanism) and one another Security Management(data encryption algorithms for authorization, sensitive user settings, etc.).

Process details survey

Let`s delineate the second process "to repair/modernize something in buildings" details.

Do it by surveying our client and/or analyst:

Question Answer
1 What to repair? 🔸 Heating system or broken floor
2 Where to repair? 🔸 In apartment(s), common room(s), whole building(s)
3 How to repair? Not important, because it`s doing by a 🔸 utility service
4 How to find a utility service? A client(an owner of REM system) has a 🔸 list of utility services with whom have active 🔸 contracts. 🔸 Call send message to them
5 What to tell them? Describe an 🔸 issue(what, where, what do you need to repair). Ask about implementation deadline and cost
6 If we agreed on the issue, then what information to save? An agreement or talk information? There is a need to document an 🔸 agreement about repair(what, who, for what cost, when...)
7 When a utility service repairs something, then do we need to document a repair 🔸 progress? Yes, document when and for what period repairing was in progress, suspend, review states
8 How to know that repair is done? 🔸 A utility service calls, sends a message with result proof documents(textual and/or image and/or sound files) via email
9 Is there a need to document the call, 🔸 to attach the documents to the issue? Yes and document that repair is done and will be reviewed
10 How to review the result? 🔸 By yourself or by assistant or by inspection of the result proofs
11 If the review was successful, then to 🔸 document that the repair was done successfully? Yes and add 🔸 e-signature to the 🔸 result document

Comment. By the symbol 🔸 are marked valuable things(i.e. entities) that potentially can be saved to a database

Process data that is represented in Entity-Relationship diagram

Comment 0. The entities are valuable things marked by 🔸 symbol in the survey.

Comment 1. Look at the diagram from the right bottom corner to the left top corner

Comment 2. The diagram is also called a database conceptual model of entities

Comment 3. It is made based on the survey and by using David Hay practices; categorization and conceptual clustering methods

Database normalization. NF:

  • To satisy 1NF all nested values are extracted to tables e.g. tasks are extracted to a table Task instead writing tasks separated by commas to Issue table Issue
  • Each table made from described entities will have records each of which has an id to satisfy 2NF
  • 3NF is satisfied e.g. Task table does not contain File(Document) table values to be without transitive dependency among task data and file data(documents).

Process steps

Let's number and name "to repair/modernize something in buildings" process steps that will be automated by REM system:

Let's categorize process steps:

Category Steps
1 Work with issue (1) describe an issue; (2) add issue tasks; (6) document repair progress
2 Work with task (2) add issue tasks; (3) find an implementer of the task; (4) to document acts of communication about task; (5) save task communication results; (6) document repair task progress; (8) review task result documents
3 Work with documents (7) get and save result documents of repair task; (8) review task result documents (9) sign task result(and other) documents
4 Work with notifications (10) send message to a manager about task progress or modernization or with result documents or with a clarification about task

Let's transform categories to classes:

💎Click to show/hide categories transformation
Process Category Unified Name Description
Work with issue IssueController Control issue state/behavior e.g. create/edit/delete issue; determine if issue is in process or suspended; get information about its tasks
Work with task IssueTaskController Control task state/behavior e.g. create/edit/delete task; add task check point; change assigned to a utility service task
Work with documents DocumentController Control work with files of different types(textual: docs, xml; visual: jpg, png; audio: mp3, wow, etc.)
Work with notifications NotificationService and CommunicationController NotificationService is a part of CommunicationController. First - controls notifications to issue or task e.g. send a notification to participants of a process. The latter(CommunicationController) is used to choose what system will be used to send messages

Let's transform steps to class functions:

💎Click to show/hide steps transformation

Comment 0. Function Name is written in a form of "ClassName=>FunctionName()".

Comment 1. A step can be made up of several functions, then in Function Name column will be written several names separated by " / " symbols e.g. step "(1) describe an issue", unified name "CreateIssue()/ChangeIssue".

Comment 2. A step can be named differently in classes. Such names are separated by commas.

Step Name ClassName=>FunctionName()
(1) describe an issue Made up of IssueController=>Create() and IssueController=>Change()
(2) add issue tasks Described in IssueController=>CreateTask() and IssueTaskController=>Create()
(3) find an implementer of the task IssueController=>FindUtilityService()
(4) to document acts of communication about task TaskController=>TaskCheckPointService=>Create()
(5) save task communication results IssueTaskController=>AddResult()
(6) to document repair task progress Described in IssueController=>IssueStateController=>Change() and TaskController=>TaskStateController=>Change() and TaskController=>TaskCheckPointService=>Create()
(7) get and save result documents of repair task Made up of DocumentController=>Add() and DocumentController=>Change()
(8) review task result documents DocumentController=>Open()
(9) sign task result(and other) documents DocumentController=>Sign()
(10) send message Made up of NotificationService=>CreateRequest() and NotificationService=>SendRequest()

Technical preferences

REM system should be written using

  • .NET 5, C#/Java, JS, NodeJs, React(microfrontend), Cucumber(E2E tests), Jasmine(JS tests)

Code

Let's sequentially transform described before "to repair/modernize something in buildings" process to code. Above were described packages and their internal structure(classes and their functions). Let's represent components of Issue Management of Real Estate Management package in a Component diagram

Component diagram

Class structure

Let's represent Issue Management and a related Account Management=>Document Management components' classes and functions in a Class diagram.

Comment 1. From Class diagram was generated C# code structure that will be used later.

Comment 2. Communication and Notification services now are not in the structure to remove a redundant complexity.

Comment 3. DocumentController can be made with E. Gamma Strategy pattern to choose with what type of document will be work

Flexibility details

Question Answer
1 Why functionality is spread across packages? Each package is a subset of independent functionality. Hence it can be reused in other systems by importing of the package and related Database, DI packages. They are encapsulated logically and physically by modifiers e.g. internal or protected, etc.
2 What is it a controller class? It is a class with an action order of a process. Each action is usually defined by a call to a service that implement the action
3 What are controller classes for? For accelerating REM system flexibility. It is easy to change action order or substitute it at all. Also, the services that are called from a controller can be changed independently and do not influence controller action order
4 How to reuse services from one package in another? Via controller class. A controller class is like a manager of a department who can find and connect his/her people with another department service to do some job
5 Why we do not extract each class function to a separate service? Such service could be reused in other components or packages It would be reused not efficiently: 1. code will be messed and hard to manage, because of too many general functions, functions' mixed domain purposes, code viscous changes(one of Design smells) 3. Will be more files and classes, therefore the code will be hard to read, then to change
6 Why interfaces? Because of SOLID principles obeying, General system theory rules adoption, etc.

Implementation details

Let's describe a way in which we will get code for a part of "to repair/modernize something in buildings" process. Consider that to repair something REM system manager needs to "(1) describe an issue", so let's create a code for this step.

First, create a scenario for "(1) describe an issue", then transform to E2E test:

Successful scenario UI test (essentials)
  1. Manager adds issue name considering BR1
  2. Manager adds issue description considering BR2
  3. Manager adds issue deadline range considering BR3
  4. Manager attaches issue documents
  5. Manager adds a comment about an issue
  6. Manager saves described issue
  1. Given open IssueCreation page
  2. When Manager enter Name according to BR1, Description(BR2), Deadline(BR3), attach document(s)(BR4)
  3. And Manager click Save button
  4. Then Manager should see message {SuccessullIssueCreation}
Extension point: User didn`t write name or description, thus fields are empty
  1. Given open IssueCreation page
  2. When Manager enter Deadline(BR3), attach document(s)(BR4)
  3. And Manager click Save button
  4. Then Manager should see message {AbsentIssueValues}
Business Rule Description
BR1 Name is longer, then 4 symbols
BR2 Description has 2 or more words
BR3 Deadline start date is equal or later, than today. Deadline end date is equal to start or later date.
BR4 Document is of docx/xml/jpg/mp3 type and document size is less, then 1 Gigabyte.

Second, considering UX/UI tests, create unit test description.

Description of unit test for sub-process "(1) describes an issue" of process "to repair/modernize something in buildings":

  1. Check if issue is not empty object
  2. Check if name and description are not empty and have values obeyed to BR1, BR2
  3. Check if issue was created by requesting new issue id from a database
  4. Check if issue documents were added by requesting each added document id from a database

Third, put unit test description to project structure that was generated from Class diagram

💎Click to show/hide comments

Comment 1. In this project is used TDD to create REM system, because it helps to capture a clear vision of domain processes and their implementation(i.e. code)

Comment 2. In some cases I translate unit test description to pseudo-code and put it to project

Comment 3. Or implement essential code in a project by myself and other is finished by a developer

Comment 4. You can found code in architectureSolution1 root

Example of what a developer gets to transform to code(with possible code constructions and descriptions)
⚠️ **GitHub.com Fallback** ⚠️