From ab26f7ade79d1fb4162b6c9666e9958b047ee6f7 Mon Sep 17 00:00:00 2001
From: Kumar Karan <74911596+kk-engineer@users.noreply.github.com>
Date: Thu, 21 Mar 2024 14:48:00 +0530
Subject: [PATCH 01/19] Adds LLD 2 and 3 notes
---
non_dsa/lld/lld_2/solid_principles_1.md | 255 ++++++++++++++++++++
non_dsa/lld/lld_2/solid_principles_2.md | 308 ++++++++++++++++++++++++
non_dsa/lld/lld_3/design_tic_tac_toe.md | 307 +++++++++++++++++++++++
3 files changed, 870 insertions(+)
create mode 100644 non_dsa/lld/lld_2/solid_principles_1.md
create mode 100644 non_dsa/lld/lld_2/solid_principles_2.md
create mode 100644 non_dsa/lld/lld_3/design_tic_tac_toe.md
diff --git a/non_dsa/lld/lld_2/solid_principles_1.md b/non_dsa/lld/lld_2/solid_principles_1.md
new file mode 100644
index 0000000..fc592a7
--- /dev/null
+++ b/non_dsa/lld/lld_2/solid_principles_1.md
@@ -0,0 +1,255 @@
+# SOLID principles 1: SRP and OCP
+- [SOLID principles](#solid-principles)
+ - [Key terms](#key-terms)
+ - [SOLID principles](#solid-principles-1)
+ - [Single responsibility principle](#single-responsibility-principle)
+ - [Open/closed principle](#openclosed-principle)
+ - [Single responsibility principle](#single-responsibility-principle-1)
+ - [Case study - Design a bird](#case-study---design-a-bird)
+ - [Reasons to follow SRP](#reasons-to-follow-srp)
+ - [How/Where to spot violations of SRP?](#howwhere-to-spot-violations-of-srp)
+ - [Side-assignment alert](#side-assignment-alert)
+ - [Open/closed principle](#openclosed-principle-1)
+ - [Abstract classes and interfaces](#abstract-classes-and-interfaces)
+ - [Interface](#interface)
+ - [When to use abstract classes and interfaces?](#when-to-use-abstract-classes-and-interfaces)
+ - [Fixing OCP violation in the `Bird` class](#fixing-ocp-violation-in-the-bird-class)
+ - [Reading List](#reading-list)
+
+## Key terms
+### SOLID principles
+> SOLID is a mnemonic acronym for five design principles intended to make object-oriented designs more understandable, flexible, and maintainable.
+
+### Single responsibility principle
+> There should never be more than one reason for a class/code unit to change. Every class should have only one responsibility.
+
+### Open/closed principle
+> Software entities (classes, modules, functions, etc.) should be open for extension, but closed for modification.
+
+## Single responsibility principle
+
+> When designing our classes, we should aim to put related features together, so whenever they tend to change they change for the same reason. And we should try to separate features if they will change for different reasons.
+
+
+ 
+
+
+The Single Responsibility Principle states that a class should do one thing, and therefore it should have only a single reason to change. Only one potential change (database logic, logging logic, and so on.) in the software’s specification should be able to affect the specification of the class.
+
+This means that if a class is a data container, like a Book class or a Student class, and it has some fields regarding that entity, it should change only when we change the data model.
+
+### Case study - Design a bird
+
+To understand the SOLID principles, let us take the help of a bird. A bird is a living creature that can fly, eat, and make a sound. How can we design a bird?
+
+The simplest solution would be to create a `Bird` class with different attributes and methods. A bird could have the following attributes:
+* Weight
+* Colour
+* Type
+* Size
+* BeakType
+
+A bird would also exhibit the following behaviours:
+* Fly
+* Eat
+* Make a sound
+
+```mermaid
+classDiagram
+ class Bird{
+ +weight: int
+ +colour: string
+ +type: string
+ +size: string
+ +beakType: string
+ +fly()
+ +eat()
+ +makeSound()
+ }
+```
+
+The `Bird` class would look as follows:
+
+```java
+public class Bird {
+ private int weight;
+ private String colour;
+ private String type;
+ private String size;
+ private String beakType;
+
+ public void fly() {
+ ...
+ }
+
+ public void eat() {
+ ...
+ }
+
+ public void makeSound() {
+ ...
+ }
+}
+```
+
+In order to understand the design further, let us try to implement the `fly` method.
+Since each bird has a different method of flying, we would have to implement conditional statements to check the type of the bird and then call the appropriate method.
+
+```java
+public void fly() {
+ if (type.equals("eagle")) {
+ flyLikeEagle();
+ } else if (type.equals("penguin")) {
+ flyLikePenguin();
+ } else if (type.equals("parrot")) {
+ flyLikeParrot();
+ }
+}
+```
+
+The above code exhibits the following problems:
+* `Readability` - The code is not readable. It is difficult to understand what the code is doing.
+* `Testing` - It is difficult to test the code. We would have to test each type of bird separately.
+* `Reusability` - The code is not reusable. If we want to re-use the code of specific type of bird, we would have to change the above code.
+* `Parallel development` - The code is not parallel development friendly. If multiple developers are working on the same code, they could face merge conflicts.
+* `Multiple reasons to change` - The code has multiple reasons to change. If we want to change the way a type of bird flies, we would have to change the code in the `fly` method.
+
+
+### Reasons to follow SRP
+Apart from overcoming the problems mentioned above, there are other reasons to follow the SRP:
+* Maintainability - Smaller, well-organized classes are easier to search than monolithic ones.
+* Ease of testing – A class with one responsibility will have far fewer test cases.
+* Lower coupling – Less functionality in a single class will have fewer dependencies.
+
+### How/Where to spot violations of SRP?
+* A method with multiple `if-else` statements. An example would be the `fly` method of the `Bird` class. This is not a silver bullet, but it is a good indicator. There can be other reasons for multiple `if-else` statements such as business logic e.g. calculating the tax, checking access rights, etc.
+* `Monster methods` or `God classes` - Methods that are too long and doing much more than the name suggests. This is a good indicator of a violation of SRP.
+
+```java
+public saveToDatabase() {
+ // Connect to database
+ // Create a query
+ // Execute the query
+ // Create a user defined object
+ // Close the connection
+}
+```
+The above method is doing much more than the name suggests. It is connecting to the database, creating a query, executing the query, creating a user defined object, and closing the connection. This method violates the SRP. It should be split into multiple methods such as `connectToDatabase`, `createQuery`, `executeQuery`, `createUserDefinedObject`, and `closeConnection`.
+* `Utility classes` - Utility classes are classes that contain only static methods which are used to perform some utility functions. Have a look at the utility package of Java [here](https://docs.oracle.com/javase/8/docs/api/java/util/package-summary.html). There is just way too many responsibilities of this package.
+
+### Side-assignment alert
+* Identify the violations of SRP in [this](../code/src/../oop/src/main/java/com/scaler/lld/questions/Invoice.java) class.
+* Refactor the code to follow SRP.
+
+---
+
+## Open/closed principle
+We identified a bunch of problems with the `Bird` class. Let us see the fly method again to spot another problem.
+
+```java
+public void fly() {
+ if (type.equals("eagle")) {
+ flyLikeEagle();
+ } else if (type.equals("penguin")) {
+ flyLikePenguin();
+ } else if (type.equals("parrot")) {
+ flyLikeParrot();
+ }
+}
+```
+
+In the above code, we are checking the type of the bird and then calling the appropriate method. If we want to add a new type of bird, we would have to change the code in the `fly` method. This is a violation of the Open/Closed Principle.
+
+
+ 
+
+
+**The Open/Closed Principle states that a class should be open for extension but closed for modification. This means that we should be able to add new functionality to the class without changing the existing code.** To add a new feature, we should ideally create a new class or method and have very little or no changes in the existing code.
+In doing so, we stop ourselves from modifying existing code and causing potential new bugs in an otherwise happy application. We should be able to add new functionality without touching the existing code for the class. This is because whenever we modify the existing code, we are taking the risk of creating potential bugs. So we should avoid touching the tested and reliable (mostly) production code if possible.
+
+* A module will be said to be open if it is still available for extension. For example, it should be possible to add fields to the data structures it contains, or new elements to the set of functions it performs.
+* A module will be said to be closed if [it] is available for use by other modules. This assumes that the module has been given a well-defined, stable description (the interface in the sense of information hiding).
+
+### Abstract classes and interfaces
+
+An abstract class is nothing but a class that is declared using the abstract keyword. It also allows us to declare method signatures using the abstract keyword (abstract method) and forces its subclasses to implement all the declared methods. Suppose if a class has a method that is abstract, then the class itself must be abstract.
+
+Abstract classes have no restrictions on field and method modifiers, while in an interface, all are public by default. We can have instance and static initialization blocks in an abstract class, whereas we can never have them in the interface. Abstract classes may also have constructors which will get executed during the child object's instantiation.
+
+Abstract classes can be defined using the `abstract` keyword. An abstract class can have abstract methods and non-abstract methods. An abstract method is a method that is declared without an implementation. It is a method that is declared using the `abstract` keyword and does not have a body. An abstract class can have a constructor and it gets executed when an object of the child class is created. An abstract class can have instance variables, static variables, instance methods, static methods, and abstract methods.
+
+```java
+public abstract class Animal {
+ private String name;
+ private int age;
+
+ public Animal(String name, int age) {
+ this.name = name;
+ this.age = age;
+ }
+
+ public abstract void makeSound();
+
+ public void eat() {
+ System.out.println("Eating...");
+ }
+}
+```
+
+#### Interface
+
+An Interface in Java programming language is defined as an abstract type used to specify the behavior of a class. An interface in Java is a blueprint of a class. A Java interface contains static constants and abstract methods. The interface in Java is a mechanism to achieve abstraction.
+
+You can think of an interface as a completely abstract class that can only contain abstract methods. An interface is similar to a class, in that it contains methods and variables, but the methods declared in an interface are by default abstract (only method signature, no body). Interfaces cannot be used to create objects (in the example above, it is not possible to create an "Animal" object). An interface is not inherited by a class; it must be implemented by a class.
+
+```java
+public interface Animal {
+ public void makeSound();
+}
+```
+
+### When to use abstract classes and interfaces?
+* If multiple classes have common functionalities, we would like to use inheritance to avoid code duplication and also have fixed contracts so that the subclasses are forced to implement the common functionalities.
+* If the common classes have common attributes, consider using abstract classes since they can have instance variables.
+* If the common classes have common methods, consider using interfaces since they can have only abstract methods. However, the implementation of the methods can be different in the subclasses. Interfaces are also useful when we want to have multiple inheritance.
+
+### Fixing OCP violation in the `Bird` class
+
+Now that we have learnt about abstract classes and interfaces, let us fix the SRP and OCP violation in the `Bird` class. In order to fix the SRP violations, we would consider having a parent class `Bird` and child classes `Eagle`, `Penguin`, and `Parrot`. Since, different birds have the same attributes and behaviours, we would want to use classes. An instance of the `Bird` class does not make sense, hence we would use an abstract class. We can't use an interface since we would want to have instance variables. We would also want to have a fixed contract for the subclasses to implement the common functionalities. Hence, we would use an abstract class.
+Now, our `Bird` class would look like this.
+
+```mermaid
+classDiagram
+ Bird <|-- Eagle
+ Bird <|-- Penguin
+ Bird <|-- Parrot
+ class Bird{
+ +weight: int
+ +colour: string
+ +type: string
+ +size: string
+ +beakType: string
+ +fly()
+ }
+ class Eagle{
+ +fly()
+ }
+ class Penguin{
+ +fly()
+ }
+ class Parrot{
+ +fly()
+ }
+```
+
+## Reading List
+* [SOLID vs CUPID vs GRASP](https://www.boldare.com/blog/solid-cupid-grasp-principles-object-oriented-design/#what-is-solid-and-why-is-it-more-than-just-an-acronym?-solid-vs.-cupid---is-the-new-always-better?)
+* [Java and SRP](https://medium.com/swlh/java-packages-and-the-single-responsibility-principle-a23e151719d1)
\ No newline at end of file
diff --git a/non_dsa/lld/lld_2/solid_principles_2.md b/non_dsa/lld/lld_2/solid_principles_2.md
new file mode 100644
index 0000000..7997912
--- /dev/null
+++ b/non_dsa/lld/lld_2/solid_principles_2.md
@@ -0,0 +1,308 @@
+# SOLID Principles 2: Liskov, Interface Segregation, and Dependency Inversion
+
+## Key Terms
+### Liskov Substitution Principle
+> Objects in a program should be replaceable with instances of their subtypes without altering the correctness of that program.
+
+### Interface Segregation Principle
+> Many client-specific interfaces are better than one general-purpose interface.
+
+### Dependency Inversion Principle
+> Depend upon abstractions. Do not depend upon concrete classes.
+
+## Liskov Substitution Principle
+
+Let us take a look at our final version of the `Bird` class from [the last session](https://github.com/kanmaytacker/fundamentals/blob/master/oop/notes/04-solid-01.md#fixing-ocp-violation-in-the-bird-class). We started with a `Bird` class which had SRP and OCP violations. We now have a `Bird` abstract class which can be extended by the `Eagle`, `Penguin` and `Parrot` subclasses.
+
+```mermaid
+classDiagram
+ Bird <|-- Eagle
+ Bird <|-- Penguin
+ Bird <|-- Parrot
+ class Bird{
+ +weight: int
+ +colour: string
+ +type: string
+ +size: string
+ +beakType: string
+ +fly()
+ }
+ class Eagle{
+ +fly()
+ }
+ class Penguin{
+ +fly()
+ }
+ class Parrot{
+ +fly()
+ }
+```
+
+We have also added a `fly()` method to the `Bird` class. All the subclasses of `Bird` have to implement this method. A penguin cannot fly, yet we have added a `fly()` method to the `Penguin` class. How can we handle this?
+* `Dummy method` - We can add a dummy method to the `Penguin` class which does nothing.
+* `Return null`
+* `Throw an exception`
+
+In the above methods, we are trying to force a contract on a class which does not follow it. If we try to use a `Penguin` object in a place where we expect a `Bird` object, we could have unexpected outcomes. For example, if we call the `fly()` method on a `Penguin` object, we would get an exception. This is not what we want. We want to be able to use a `Penguin` object in a place where we expect a `Bird` object. We want to be able to call the `fly()` method on a `Penguin` object and get the same result as if we had called it on a `Sparrow` object. This is where the Liskov Substitution Principle comes into play.
+
+```java
+List birds = List.of(new Eagle(), new Penguin(), new Parrot());
+for (Bird bird : birds) {
+ bird.fly();
+}
+```
+This is a violation of the Liskov Substitution Principle. The Liskov Substitution Principle states that objects in a program should be replaceable with instances of their subtypes without altering the correctness of that program. In other words, if we have a `Bird` object, we should be able to replace it with an instance of its subclasses without altering the correctness of the program. In our case, we cannot replace a `Bird` object with a `Penguin` object because the `Penguin` object requires special handling.
+
+
+
+### Creating new abstract classes
+
+A way to solve the issue with the `Penguin` class is to create a new set of abstract classes, `FlyableBird` and `NonFlyableBird`. The `FlyableBird` class will have the `fly()` method and the `NonFlyableBird` class will not have the `fly()` method. The `Penguin` class will extend the `NonFlyableBird` class and the `Eagle` and `Parrot` classes will extend the `FlyableBird` class. This way, we can ensure that the `Penguin` class does not have to implement the `fly()` method.
+
+```mermaid
+classDiagram
+ class Bird{
+ +weight: int
+ +colour: string
+ +type: string
+ +size: string
+ +beakType: string
+ }
+ class FlyableBird{
+ +fly()
+ }
+ Bird <|-- FlyableBird
+ FlyableBird <|-- Eagle
+ FlyableBird <|-- Parrot
+
+ class NonFlyableBird{
+ +eat()
+ }
+ Bird <|-- NonFlyableBird
+ NonFlyableBird <|-- Penguin
+
+ class Eagle{
+ +fly()
+ }
+ class Penguin{
+ +eat()
+ }
+ class Parrot{
+ +fly()
+ }
+```
+
+This is an example of multi-level inheritance. The issue with the above approach is that we are tying behaviour to the class hierarchy. If we want to add a new type of behaviour, we will have to add a new abstract class. For instance if we can have birds that can swim and birds that cannot swim, we will have to create a new abstract class `SwimableBird` and `NonSwimableBird` and add them to the class hierarchy. But now how do you extends from two abstract classes? You can't. Then we would have to create classes with composite behaviours such as `SwimableFlyableBird` and `SwimableNonFlyableBird`.
+
+```mermaid
+classDiagram
+ class Bird{
+ +weight: int
+ +colour: string
+ +type: string
+ +size: string
+ +beakType: string
+ }
+ class SwimableFlyableBird{
+ +fly()
+ +swim()
+ }
+ Bird <|-- SwimableFlyableBird
+ SwimableFlyableBird <|-- Swan
+
+ class NonSwimableFlyableBird{
+ +fly()
+ }
+ Bird <|-- NonSwimableFlyableBird
+ NonSwimableFlyableBird <|-- Eagle
+
+ class SwimableNonFlyableBird{
+ +swim()
+ }
+
+ Bird <|-- SwimableNonFlyableBird
+ SwimableNonFlyableBird <|-- Penguin
+
+ class NonSwimableNonFlyableBird{
+ +eat()
+ }
+
+ Bird <|-- NonSwimableNonFlyableBird
+ NonSwimableNonFlyableBird <|-- Toy Bird
+
+ class Swan{
+ +fly()
+ +swim()
+ }
+
+ class Eagle{
+ +fly()
+ }
+
+ class Penguin{
+ +eat()
+ }
+
+ class Toy Bird{
+ +makeSound()
+ }
+```
+
+If we want to add a new type of behaviour, we will have to add a new abstract class. This is why we should not tie behaviour to the class hierarchy.
+
+### Creating new interfaces
+
+We can solve the issue with the `Penguin` class by creating new interfaces. We can create an `Flyable` interface and an `Swimmable` interface. The `Penguin` class will implement the `Swimmable` interface and the `Eagle` and `Parrot` classes will implement the `Flyable` interface. This way, we can ensure that the `Penguin` class does not have to implement the `fly()` method.
+
+```mermaid
+classDiagram
+ class Bird{
+ <>
+ +weight: int
+ +colour: string
+ +type: string
+ +size: string
+ +beakType: string
+
+ +makeSound()
+ }
+
+ Bird <|-- Eagle
+ Bird <|-- Parrot
+ Bird <|-- Penguin
+ class Flyable{
+ <>
+ +fly()*
+ }
+ Flyable <|-- Eagle
+ Flyable <|-- Parrot
+
+ class Swimmable{
+ <>
+ +swim()*
+ }
+ Swimmable <|-- Penguin
+
+ class Eagle{
+ +fly()
+ }
+ class Penguin{
+ +swim()
+ }
+ class Parrot{
+ +fly()
+ }
+```
+
+Since we are not tying behaviour to the class hierarchy, we can add new types of behaviour without having to add new abstract classes. For instance, if we want to add a new type of behaviour, we can create a new interface `CanSing` and add it to the class hierarchy.
+
+### Summary
+* The Liskov Substitution Principle states that objects in a program should be replaceable with instances of their subtypes without altering the correctness of that program.
+* To identify violations, we can check if we can replace a class with its subclasses having to handle special cases and expect the same behaviour.
+* Prefer using interfaces over abstract classes to implement behaviour since abstract classes tend to tie behaviour to the class hierarchy.
+
+## Interface Segregation Principle
+
+Segregation means keeping things separated, and the Interface Segregation Principle is about separating the interfaces.
+
+The principle states that many client-specific interfaces are better than one general-purpose interface. Clients should not be forced to implement a function they do no need. Declaring methods in an interface that the client doesn’t need pollutes the interface and leads to a “bulky” or “fat” interface
+
+
+
+A client should never be forced to implement an interface that it doesn’t use, or clients shouldn’t be forced to depend on methods they do not use. In other words, we should not create fat interfaces. A fat interface is an interface that has too many methods. If we have a fat interface, we will have to implement all the methods in the interface even if we don’t use them. This is known as the interface segregation principle.
+
+Let us take the example of our `Bird` class. To not tie the behaviour to the class hierarchy, we created an interface `Flyable` and implemented it in the `Eagle` and `Parrot` classes.
+
+```java
+public interface Flyable {
+ void fly();
+ void makeSound();
+}
+```
+Along with the `fly()` method, we also have the `makeSound()` method in the `Flyable` interface. This is because the `Eagle` and `Parrot` classes both make sounds when they fly. But what if we have a class that implements the `Flyable` interface? The class does not make a sound when it flies. This is a violation of the interface segregation principle. We should not have the `makeSound()` method in the `Flyable` interface.
+
+Larger interfaces should be split into smaller ones. By doing so, we can ensure that implementing classes only need to be concerned about the methods that are of interest to them. If a class exposes so many members that those members can be broken down into groups that serve different clients that don’t use members from the other groups, you should think about exposing those member groups as separate interfaces.
+
+Precise application design and correct abstraction is the key behind the Interface Segregation Principle. Though it'll take more time and effort in the design phase of an application and might increase the code complexity, in the end, we get a flexible code.
+
+## Dependency Inversion Principle
+The principle of dependency inversion refers to the decoupling of software modules. This way, instead of high-level modules depending on low-level modules, both will depend on abstractions. If the OCP states the goal of OO architecture, the DIP states the primary mechanism for achieving that goal.
+
+The general idea of this principle is as simple as it is important: High-level modules, which provide complex logic, should be easily reusable and unaffected by changes in low-level modules, which provide utility features. To achieve that, you need to introduce an abstraction that decouples the high-level and low-level modules from each other. Dependency inversion principle consists of two parts:
+* High-level modules should not depend on low-level modules. Both should depend on abstractions.
+* Abstractions should not depend on details. Details should depend on abstractions.
+
+
+
+Our bird class looks pretty neat now. We have separated the behaviour into different lean interfaces which are implemented by the classes that need them. When we add new sub-classes we identify an issue. For birds that have the same behaviour, we have to implement the same behaviour multiple times.
+
+```java
+public class Eagle implements Flyable {
+ @Override
+ public void fly() {
+ System.out.println("Eagle is gliding");
+ }
+}
+
+public class Sparrow implements Flyable {
+ @Override
+ public void fly() {
+ System.out.println("Sparrow is gliding");
+ }
+}
+```
+
+The above can be solved by adding a default method to the `Flyable` interface. This way, we can avoid code duplication.
+But which method should be the default implementation? What if in future we add more birds that have the same behaviour? We will have to change the default implementation or either duplicate the code.
+
+Instead of default implementations, let us abstract the common behaviours to a separate helper classes. We will create a `GlidingBehaviour` class and a `FlappingBehaviour` class. The `Eagle` and `Sparrow` classes will implement the `Flyable` interface and use the `GlidingBehaviour` class. The `Parrot` class will implement the `Flyable` interface and use the `FlappingBehaviour` class.
+
+```java
+public class Eagle implements Flyable {
+ private GlidingBehaviour glidingBehaviour;
+
+ public Eagle() {
+ this.glidingBehaviour = new GlidingBehaviour();
+ }
+
+ @Override
+ public void fly() {
+ glidingBehaviour.fly();
+ }
+}
+```
+
+Now we have a problem. The `Eagle` class is tightly coupled to the `GlidingBehaviour` class. If we want to change the behaviour of the `Eagle` class, we will have to open the Eagle class to change the behaviour. This is a violation of the dependency inversion principle. We should not depend on concrete classes. We should depend on abstractions.
+
+Naturally, we rely on interfaces as the abstraction. We create a new interface `FlyingBehaviour` and implement it in the `GlidingBehaviour` and `FlappingBehaviour` classes. The `Eagle` class will now depend on the `FlyingBehaviour` interface.
+
+
+```java
+ interface FlyingBehaviour{
+ void fly()
+ }
+ class GlidingBehaviour implements FlyingBehaviour{
+ @Override
+ public void fly() {
+ System.out.println("Eagle is gliding");
+ }
+ }
+ ...
+
+ class Eagle implements Flyable {
+ private FlyingBehaviour flyingBehaviour;
+
+ public Eagle() {
+ this.flyingBehaviour = new GlidingBehaviour();
+ }
+
+ @Override
+ public void fly() {
+ flyingBehaviour.fly();
+ }
+ }
+```
+
+## Reading list
+* [LSP](http://web.archive.org/web/20151128004108/http://www.objectmentor.com/resources/articles/lsp.pdf)
+* [SOLID - Recap](https://www.cs.odu.edu/~zeil/cs330/latest/Public/solid/)
\ No newline at end of file
diff --git a/non_dsa/lld/lld_3/design_tic_tac_toe.md b/non_dsa/lld/lld_3/design_tic_tac_toe.md
new file mode 100644
index 0000000..3bdbb69
--- /dev/null
+++ b/non_dsa/lld/lld_3/design_tic_tac_toe.md
@@ -0,0 +1,307 @@
+# Design Tic-Tac-Toe
+
+## What is Tic-Tac-Toe?
+
+TicTacToe is a 2 player game played on a 3 x 3 board. Each player is allotted a symbol (one X and one O). Initially, the board is empty. Alternatively, each player takes a turn and puts their symbol at any empty slot. The first player to get their symbol over a complete row OR a complete column OR a diagonal wins.
+
+You can play the game within Google Search by just searching for “tictactoe”!
+
+
+
+
+## Questions to Ask
+* Will the game be played amongst only 2 players or can there be any number of players in future?
+* Is the board size restricted to 3x3 or can it be any NxN?
+* Can there be different ways to win?
+* Can one of the players be a bot?
+* Feature Suggestions:
+ * Do we want to time a move? Skip/ Declare the other person as winner if the move doesn’t happen within x seconds.
+ * Do we want to support undo operation?
+ * Can there be some players who are just watching? Not playing.
+ * Do we want to store analytics? Basically previous games, who played what move etc.
+ * Support for tournaments? Basically a set of matches, each match between 2 players of the tournament.
+
+## Expectations
+* The code should be working and functionally correct
+* Good software design practices should be followed:
+* Code should be modular, readable, extensible
+* Separation of concern should be addressed
+* Project structured well across multiple files/ packages
+* Write unit tests
+* No need of GUI
+
+
+## Problem Requirements
+* Board can be of any NxN size.
+* There can be two players.
+* Each player will be allotted a symbol.
+* The symbol can be one of O and X.
+* The players can be either humans or bots.
+* Each human player will have a name, email and profile image.
+* Each bot player will have a difficulty level.
+* Any random player can start the game.
+* Then the players will take turns alternatively.
+* The player with any consecutive N symbols in a row, column or diagonal wins.
+* If the board is full and no player has won, the game is a draw.
+
+## Entities and their attributes
+* Game
+ * Board
+ * Players
+* Board
+ * Cells
+* Cell
+ * Row
+ * Column
+ * Symbol
+* Human Player
+ * Name
+ * Email
+ * Profile Image
+* Bot Player
+ * Difficulty Level
+
+## Design
+
+### Use Case Diagram
+```plantuml
+@startuml
+left to right direction
+actor HumanPlayer
+actor Bot
+rectangle Game {
+ HumanPlayer -- (Start Game)
+ HumanPlayer -- (Make Move)
+ Bot -- (Make Move)
+ HumanPlayer -- (Register)
+
+ (Make Move) .> (Check Winner) : includes
+}
+
+@enduml
+```
+
+### Initial Design
+
+```mermaid
+classDiagram
+ class Game {
+ -Board board
+ -HumanPlayer humanPlayer
+ -BotPlayer botPlayer
+ +register(HumanPlayer) HumanPlayer
+ +startGame(HumanPlayer, BotPlayer, int row, int column) Board
+ +makeMove(PlayerId, int, int) Board
+ +checkWinner(Board, HumanPlayer, BotPlayer) int
+ }
+
+ class Board {
+ -Cell[][] cells
+ +Board(int, int) : Board
+ }
+
+ class Cell {
+ -int x
+ -int y
+ -Symbol symbol
+ }
+
+ class HumanPlayer {
+ -int id
+ -String name
+ -String email
+ -Byte[] photo
+ -Symbol symbol
+ +play(Board) Cell
+ }
+
+ class BotPlayer {
+ -int id
+ -Level level
+ -Symbol symbol
+ +play(Board) Cell
+ }
+
+ Game "1" --* "1" Board
+ Board "1" --* "*" Cell
+
+ Game "1" --* "1" BotPlayer
+ Game "1" --* "1" HumanPlayer
+```
+
+* There is no common contract for players. Parent class to represent all different types of players.
+* There is tight coupling between Game and different types of players. It is not extensible to support multiple players
+* OCP and SRP violation in play method.
+* Huge memory consumption - multiple instances of the player will be created for multiple games. Each instance has a new photo.
+
+## Common contract - Player abstract class
+
+- Common behaviour - `play`
+- Common attributes - `Symbol`
+
+```mermaid
+classDiagram
+
+ class Game {
+ -Board board
+ -Player[] players
+ }
+
+ class Player {
+ <>
+ -Symbol symbol
+ +play(Board)* Cell
+ }
+
+ class HumanPlayer {
+ -String name
+ -String email
+ -Byte[] photo
+ +play(Board) Cell
+ }
+
+ class BotPlayer {
+ -Level level
+ +play(Board) Cell
+ }
+
+ Player <|-- HumanPlayer
+ Player <|-- BotPlayer
+
+ Game "1" --* "*" Player
+```
+
+* ~~There is no common contract for players. Parent class to represent all different types of players.~~
+* ~~There is tight coupling between Game and different types of players. It is not extensible to support multiple players~~
+* OCP and SRP violation in play method.
+* Huge memory consumption - multiple instances of the player will be created for multiple games. Each instance has a new photo.
+
+## Tight coupling
+-HumanPlayer
+-BotPlayer
+-Player[] players
+``mermaid
+``
+
+
+## OCP and SRP violation in play method - Strategy
+
+## Huge memory consumption - Flyweight
+
+- Paul Morphy
+- Instance 1 -
+ - name - Paul Morphy
+ - email - paul@blind.in
+ - photo - 5MB
+ - symbol - O
+- Instance 2 -
+ - name - Paul Morphy
+ - email - paul@blind.in
+ - photo - 5MB
+ - symbol - X
+
+- Store fields that do not change in a class - Intrinsic state
+- Store field that change in a class - Extrinsic state
+
+
+```mermaid
+classDiagram
+ class Game {
+ -Board board
+ -Player[] players
+ }
+
+ class Player {
+ <>
+ -Symbol symbol
+ +play(Board)* Cell
+ }
+
+ class User {
+ -String name
+ -String email
+ -Byte[] photo
+ }
+
+ class HumanPlayer {
+ -User user
+ +play(Board) Cell
+ }
+
+ Player <|-- HumanPlayer
+ Game "1" --* "*" Player
+
+ HumanPlayer "*" --o "1" User
+
+```
+
+* Problems so far
+* OCP and SRP violation in play method.
+
+
+### Implement different levels in a bot
+
+```java
+
+class BotPlayer {
+
+ private Level level;
+
+ private Cell play(Board board) {
+ switch (level) {
+ case EASY:
+ // Really easy move
+ case MEDIUM:
+ // Medium level moves
+ }
+ }
+}
+```
+
+```mermaid
+classDiagram
+ class BotPlayer {
+ -int id
+ -Level level
+ -Symbol symbol
+ -PlayingStrategy strategy
+ +play(Board) Cell
+ }
+
+ class PlayingStrategy {
+ <>
+ +play(Board) Cell
+ }
+
+ class RandomPlayingStrategy {
+ +play(Board) Cell
+ }
+
+ class MinMaxPlayingStrategy {
+ +play(Board) Cell
+ }
+
+ class AlphaBetaPlayingStrategy {
+ +play(Board) Cell
+ }
+
+ PlayingStrategy <|-- RandomPlayingStrategy
+
+ PlayingStrategy <|-- MinMaxPlayingStrategy
+
+ PlayingStrategy <|-- AlphaBetaPlayingStrategy
+
+ BotPlayer "*" --o "1" PlayingStrategy
+
+```
+
+* Inject different behaviours
+* Such that they can be reused
+ * Strategy Design pattern
+
+
+* There is no common contract for players. Parent class to represent all different types of players. - Abstract classes
+* There is tight coupling between Game and different types of players. It is not extensible to support multiple players - `List`
+* OCP and SRP violation in play method.
+ - Strategy pattern
+* Huge memory consumption - multiple instances of the player will be created for multiple games. Each instance has a new photo. - Flyweight
\ No newline at end of file
From ddd7374000acb3d9e7239ad89a44fdf4d2afa1a0 Mon Sep 17 00:00:00 2001
From: Kumar Karan <74911596+kk-engineer@users.noreply.github.com>
Date: Thu, 21 Mar 2024 15:00:49 +0530
Subject: [PATCH 02/19] Add HLD pdf notes
---
non_dsa/hld/NoSQL Contd..pdf | Bin 0 -> 299556 bytes
... Theorem, PACELC Theorem & Master-Slave.pdf | Bin 0 -> 407166 bytes
non_dsa/hld/System Design - Caching 1.pdf | Bin 0 -> 268256 bytes
.../System Design - Caching Contd..docx.pdf | Bin 0 -> 223756 bytes
.../System Design - Case Study -Typeahead.pdf | Bin 0 -> 476852 bytes
non_dsa/hld/System Design - SQL vs NoSQL.pdf | Bin 0 -> 244618 bytes
.../System Design 101 & Consistent Hashing.pdf | Bin 0 -> 714733 bytes
7 files changed, 0 insertions(+), 0 deletions(-)
create mode 100644 non_dsa/hld/NoSQL Contd..pdf
create mode 100644 non_dsa/hld/System Design - CAP Theorem, PACELC Theorem & Master-Slave.pdf
create mode 100644 non_dsa/hld/System Design - Caching 1.pdf
create mode 100644 non_dsa/hld/System Design - Caching Contd..docx.pdf
create mode 100644 non_dsa/hld/System Design - Case Study -Typeahead.pdf
create mode 100644 non_dsa/hld/System Design - SQL vs NoSQL.pdf
create mode 100644 non_dsa/hld/System Design 101 & Consistent Hashing.pdf
diff --git a/non_dsa/hld/NoSQL Contd..pdf b/non_dsa/hld/NoSQL Contd..pdf
new file mode 100644
index 0000000000000000000000000000000000000000..93ef059f0b7d40a90fb01938d04d973352fe8bbe
GIT binary patch
literal 299556
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