# Preface My [[PDW|Personal Data Warehouse]] is a excellent source of [[Project-Based Learning]]. I already made an [[Enterprise Architecture of the PDW]] - that was enlightening, but a stretch for what EA is all about. That is not the case for the [[C4 Model]] - it's *squarely aimed* at things like the PDW. I am, however, not **at all** an expert in any of this. There's a solid chance I'd get slapped on the wrist for mistakes I'm not aware of by Simon Brown, the creator of the C4 technique. Tooling: [[DrawIO]] # C4 Model *Note: I'm not an expert at this.* ## System Context What the system is. Who uses it. How it interacts with its environment. ![[PDW_Context.png]] ## Container The highest-level "containers" of functionality, drilling in one level to the PDW block from the System Context model above. ![[PDW_Containers.png]] ## Components In accordance with [the "official" recommendations](https://c4model.com/diagrams/component), I did not create component diagrams because they didn't seem to add value. ## Code I'm not sure if this is "proper" C4 technique, but there are some conceptual-level things that describe the system well that aren't covered in any of the above. I'm skipping "Components" and showing some code-type diagrams. ### Important Interfaces The PDW is basically just a series of **data interfaces**, and some tools to work with them. ![[PDW_Conceptual_Data.png]] ### Important Operations The `DataJournal` class contains static methods for carrying out these "main" operations on Data Journal *objects*. ![[PDW_Main_Processes.png]] ### Merge Algorithm A simple-*ish* flowchart describing the Merge algorithm - illustrates why all elements (i.e. `Def`s and `Entry`s) **need** the keys `_id` and `_updated`. ![[PDW_Merge_Algorithm.png]] ### Connectors, Translators, & Utility Classes A simple list of existing capabilities (and some planned ones, marked in grey). ![[PDW_Connectors_Translators_Utilities.png]] # ADRs An couple examples of [[Architecture Decision Records]]. This is not *technically* part of the C4 model, but is recommended by Simon Brown, the creator of the C4 model. ## Using a Radix-36 String for Timestamps ```plaintext --- status: accepted date: 2024-08-21 --- # Use radix-36 strings as timestamps ## Context and Problem Statement Elements in the PDW need to be timestamped with absolute references to *when* they were updated to enable data merging and general maintenance. Also PDW is meant to be uncoupled from and not bound to any **one** data tool. Different data tools approach timestamps differenty from one-another, and often are in conflict. Notably, Microsoft Excel causes problems with both storing timestamps as human-readable text dates and storing them as large numbers. A solution is needed to ensure a consistent canonical data model can be maintained without interpretation errors. The timestamp needs to be alphabetically sortable and relatively short. Also there is a desire for a lightweight solution that does not necessitate including large chunks of code for handling timestamping. ## Decision Drivers * Unambiguous * Portable * Tooling-independent * Consistent * Sortable ## Considered Options * Radix-36 strings * ISO-8601 strings ending with "Z" * ISO-8601 strings ending with timezone ## Decision Outcome Chosen option: "Radix-36 Strings", because it is completely platform-independent and requires the same standard approach regardless of the tool being used. It is not interpreted by *any* tool as a date, therefore *every* tool will require translation into & out of. ### Consequences * Good, because they are portable, sortable, and consistent due to their tooling-independence * Bad, because they are not human-readable * Good, because they can be unambiguously to/from Dates with a single line of JS ## Pros and Cons of the Options ### Radix-36 Strings * See Consequences, above. ### ISO-8601 Strings ending with "Z" * Good, because they are sortable and consistent * Good, because they are an ISO Standard * Neutral, because they are human-readable-*ish* * Bad, because they introduce timezone issues when the "Z" is imporperly handled * Bad, because *some* tools recognize them while others, don't leading to inconsistency ### ISO-8601 Strings ending with Timezone * Good, because they are human-readable and consistent * Good, because they are an ISO Standard * Bad, because they are not sortable via standard string comparison * Bad, because they introduce timezone issues when the timezone suffix is imporperly handled * Bad, because *some* tools recognize them while others don't, leading to inconsistency ## More Information The two lines of JavaScript necessary to translate in both directions. function makeEpochStrFrom(stringOrDate: string | Date): EpochStr { return new Date(stringOrDate).getTime().toString(36); } function parseDateFromEpochStr(epochStr: EpochStr): Date { return new Date(parseInt(epochStr, 36)) } ``` ## Prefer Functional Patterns over Object-Orientation ```plaintext --- status: accepted date: 2024-10-21 --- # Prefer Functional Patterns over Object-Orientation ## Context and Problem Statement The previous version of the system was built using Object-Oriented methods. As the system scaled, the complexities of state management made things increasingly difficult. Upon system refactoring, a decision needed made about whether an `Entry` and a `Def` should be *class instances*, with implied associated lifecycles, or simply objects of a certain shape. ## Decision Drivers * Ease of development * Ease of code reuse * Speed of code execution ## Considered Options * Prefer functional patterns. * Prefer Object-Orientation ## Decision Outcome Chosen option: "Prefer functional patterns", because it allows complete segmentation of the system and the cleanest approach to code reuse, despite requiring a substantial lift up front. ### Consequences * Good, because components are now **only** *interface*-dependent and are highly modularized/reusable * Neutral, because some use cases take on a performance hit whereas others are improvements * Neutral, because some forced ergonomics changes are tedious whereas others are improvements * Bad, because it's a complete refactor & almost no existing code or patterns can be ported over ```