Linked handout: 8. Software design and architecture

Software design and architecture

We have already touched on design a lot

Today we will cover

Software design and architecture

Today we will cover

  • Communicating design / architecture
  • Design on all levels of architecture
  • What are "design" vs "architecture" decisions
  • What goes into decisions
    • Predictions
    • Scope
    • Experience
    • Requirements
    • ...
  • Consequences of decisions
  • Practical examples

Software design and architecture

  • Communicating design / architecture

The usual: visual representation + live explanation

Success rate: questionable

    The suggestion: design the design / architecture presentation properly

  • Should it be stand-alone?
  • What story should it tell?
  • Who are you telling it to?

Software design and architecture

  • Communicating design / architecture

A good place to start: the C4 model
c4model.com/

  • Level 1: Context
  • Level 2: Containers (i.e. Environments)
  • Level 3: Components
  • Level 4: Code

Great introductory video in the handout - here quick summary

Software design and architecture

  • Communicating design / architecture
  • Level 1: Context

Software design and architecture

  • Communicating design / architecture
  • Level 1: Context
  • This tells me how the Users interact with the system and what external connections are made
  • This should reflect the real-world usage of the system
  • Its a map that should help me understand the context
  • Even if this diagram is often trivial in research software it might not be!

Software design and architecture

  • Communicating design / architecture
  • Level 1: Context
  • Level 2: Containers (i.e. Environments)
  • Level 3: Components
  • Level 4: Code

Software design and architecture

  • Communicating design / architecture
  • Level 2: Containers (i.e. Environments)

Software design and architecture

  • Communicating design / architecture
  • Level 2: Containers (i.e. Environments)
  • This tells you what environments you need to manage and how they interface with each other
  • These should be reflected in your deployment, build, dependency, and API management
  • Its a map that should help me navigate and understand

Software design and architecture

  • Communicating design / architecture
  • Level 1: Context
  • Level 2: Containers (i.e. Environments)
  • Level 3: Components
  • Level 4: Code

Software design and architecture

  • Communicating design / architecture
  • Level 3: Components

Software design and architecture

  • Communicating design / architecture
  • Level 3: Components
  • This architecture should be reflected in the code!
  • Think modules, subpackages, protocols, classes ...
  • Its a map that should help me navigate and understand

Software design and architecture

  • Communicating design / architecture
  • Level 4: Code
  • You should (in almost all cases) not draw these
  • Read the code/docs instead
  • Or auto-generate them from the code

Software design and architecture

  • Communicating design / architecture
  • Level 4: Code

Here is the call-graph of a simple TCP client Request call

Software design and architecture

  • Communicating design / architecture

A few other useful diagram types

  • Functional diagrams
  • State diagrams
  • Sequence diagrams

Software design and architecture

  • Communicating design / architecture
  • Functional diagrams

Functional diagrams showcase a system's functional processes and how they interact (it does not have to reflect architecture)

For our field, these are usually 1-to-1 with control and data flow diagrams

Software design and architecture

  • Communicating design / architecture

A few other useful diagram types

  • Functional diagrams
  • State diagrams
  • Sequence diagrams

Software design and architecture

  • Communicating design / architecture
  • State diagrams

Software design and architecture

  • Communicating design / architecture
  • Functional diagrams
  • State diagrams
  • Sequence diagrams

Software design and architecture

  • Communicating design / architecture
  • Sequence diagrams

Describes not only what occurs but also in what order

Software design and architecture

Today we will cover

  • Communicating design / architecture
  • Design on all levels of architecture
  • What are "design" vs "architecture" decisions
  • What goes into decisions
  • Consequences of decisions
  • Practical examples

Software design and architecture

  • Design on all levels of architecture

Design decisions on different levels have different consequences

Example: A solar-system dynamics simulation tool

Level 1 Context example - where do I get my data?

Software design and architecture

  • Design on all levels of architecture

Level 1 Context example - where do I get my data?

Software design and architecture

  • Design on all levels of architecture

Level 1 Context example - where do I get my data?

Instead include the Kernel parsing as a component

Pros vs Cons?

Software design and architecture

  • Design on all levels of architecture

Level 1 Context example - where do I get my data?

  • Option 1: Only simple API call needed, dependant on network, not reproducible, no kernel choice
  • Option 2: Requires manual kernel parsing, offline, reproducible, completely configurable, requires more space and the kernels on runtime
  • Which one is better?

Software design and architecture

  • Design on all levels of architecture

Level 2 Container example - How do I view the results?

Software design and architecture

  • Design on all levels of architecture

Level 2 Container example - How do I view the results?

Software design and architecture

  • Design on all levels of architecture

Level 2 Container example - How do I view the results?

  • Option 1: A server that streams the resulting video
    • No client requirements (except video receive)
    • Server side calculations
    • Limited user control possible
  • Option 2: A viewer that renders the results in a GUI
    • User must compile/run viewer
    • User must download/access all data and have sufficient hardware
    • Total user control possible
  • Which one is better?

Software design and architecture

  • Design on all levels of architecture

Level 3 Component example - How do I visualize the data?

  • Option 1: Static
    • No real-time rendering requirement
    • Simple interface, slow user exploration
    • Simple / flexible implementation
  • Option 2: Interactive
    • Real-time rendering
    • Interactive UI, fast user exploration
    • Complex GPU implementation
  • Which one is better?

Software design and architecture

  • Design on all levels of architecture

Level 4 Code example - How do I represent the data?

                    
                        class Position3D:
                            def __init__(self, x, y, z):
                                self.x = x
                                self.y = y
                                self.z = z


                        class Velocity3D:
                            def __init__(self, vx, vy, vz):
                                self.vx = vx
                                self.vy = vy
                                self.vz = vz


                        class State:
                            def __init__(self, pos: Position3D, vel: Velocity3D, identifier):
                                self.position = pos
                                self.velocity = vel
                                self.identifier = identifier
                                self.next = None


                        class Simulation:
                            def __init__(self, file):
                                self.head = None
                                current = None
                                for identifier, state in read_simulation(file):
                                    s = State(
                                        Position3D(state[0], state[1], state[2]),
                                        Velocity3D(state[3], state[4], state[5]),
                                        identifier,
                                    )
                                    if current is not None:
                                        current.next = s 
                                    current = s
                                    if self.head is None:
                                        self.head = s

Versus

Software design and architecture

  • Design on all levels of architecture

Level 4 Code example - How do I represent the data?

                    
                        from dataclasses import dataclass, field
                        import numpy as np
                        import numpy.typing as npt


                        @dataclass
                        class States:
                            positions: npt.NDArray[np.float64]
                            velocities: npt.NDArray[np.float64]
                            ids: npt.NDArray[np.dtype("U8")]
                            objects: dict[np.dtype("U8"), int] = field(init=False)

                            def __post_init__(self):
                                self.objects = {obj: ind for ind, obj in enumerate(self.ids)}

                        def load_simulation(file) -> States:
                            states, ids = read_simulation(file)
                            return States(
                                positions=states[:3, :],
                                velocities=states[3:, :],
                                ids=ids,
                            )

Why? See this and previous handouts

Software design and architecture

  • Communicating design / architecture
  • Design on all levels of architecture
  • What are "design" vs "architecture" decisions
  • What goes into decisions
  • Consequences of decisions
  • Practical examples

Software design and architecture

  • What are "design" vs "architecture" decisions

My definition is

  • Architecture decisions

    • How the software system will function and what it shall do
    (can be multiple architectures that fulfill requirements)

    C4 Level 1-3

  • Design decisions

    • Multiple implementations that solve the same problem
    (i.e. "free variables", not obvious which is the best)

    C4 Level 4

Software design and architecture

  • What are "design" vs "architecture" decisions

My definition is

  • Architecture decisions

    • We saw example before of these

  • Design decisions

Software design and architecture

  • What are "design" vs "architecture" decisions
  • Design decisions

An example: a table with schedule data used in processing

  1. pandas DataFrame
  2. dataclass with numpy vectors

Everything we need can be done in both

Software design and architecture

  • What are "design" vs "architecture" decisions
  • Design decisions

An example: a table with schedule data used in processing

Everything we need can be done in both

  • Which one is easier to implement?
  • Which one will be easier to read/maintain?
  • Is pandas used elsewhere?
  • Will we do more complex queries later?
  • Is it easy to change our minds later?
  • Is this performance critical?
  • Which is more performant?

Software design and architecture

  • Communicating design / architecture
  • Design on all levels of architecture
  • What are "design" vs "architecture" decisions
  • What goes into decisions
  • Consequences of decisions
  • Practical examples

Software design and architecture

  • What goes into decisions
  • Consequences of decisions

Software design and architecture

  • What goes into decisions

    • Boring answer: everything that matters

  • Consequences of decisions

    • Boring answer: depends on the situation

My suggestion?
Try to predict the consequences and let those that matter guide you

Some factors to consider:

Software design and architecture

  • What goes into decisions
  • Consequences of decisions

Some factors to consider:

  • Compatibility
  • Extensibility
  • Modularity
  • Fault-tolerance/Robustness
  • Maintainability
  • Reusability
  • Security
  • Usability
  • Performance
  • Portability
  • Scalability

Software design and architecture

  • What goes into decisions
  • Consequences of decisions

These come from a master thesis I supervised a while ago

The Efficiency of Good Software Practices: A Case Study on a Radar Meteor Analysis Software Rewrite

TL;DR Conclusions

good software practices do matter and improve the factors
and the suggested factors are important (depending on the project)

Software design and architecture

Today we will cover

  • Communicating design / architecture
  • Design on all levels of architecture
  • What are "design" vs "architecture" decisions
  • What goes into decisions
  • Consequences of decisions
  • Practical examples

Software design and architecture

Today we will cover

  • Practical examples

See handouts