V
Notenik Architecture
V
*
Introduction
Notenik is an object-oriented software architecture for creating, storing, maintaining, reading and sharing Notes. Notes are objects containing various bits of text.
>
Design Trade-Offs
*
Simplicity over infinite variability.
*
Common use cases over edge cases.
*
Resilience over fussiness.
*
Loose coupling over monolithic.
V
>
Data Architecture
The Notenik architecture includes the following major objects.
V
*
User
A user has access to one or more Collections.
V
*
Provider
A Provider provides the operating and storage context for one or more Realms.
A Provider is an organization or person that hosts an instance of the Notenik software and makes it accessible on the Web through a domain name owned by the Provider.
Notenik is intended to be available from any number of Providers. In this sense, it is similar to email, and dissimilar from Facebook and Twitter.
Each provider is responsible for its own sustainable business model. A provider may be a for-profit or a nonprofit. The provider may charge users for use of content stored by the provider. It may also charge users a fee for reading some or all of its content.
V
*
Realm
A Realm identifies ownership/stewardship for one or more Collections contained within.
Within the context of Notenik, a Realm exercises stewardship over the content that exists within that Realm.
Each Realm is hosted by a particular Provider.
A single realm may correspond to a single individual or an organization composed of multiple individuals.
The Realm establishes the rules for ownership and licensing of content created within that Realm, and the general rules for accessing its content.
Each Realm will have a name and a path, with the path typically being based on the name. Both name and path must be unique within a Provider.
As an example, let's say that I create a realm for Herb Bowie within the provider at notenik.net. So the path for this realm might be hbowie, resulting in a URL of notenik.net/hbowie.
The null realm represents the realm of the provider. So Herb Bowie might also have a Notenik realm at the url hbowie.com.
V
*
Collection
A Collection contains one or more Notes.
Each Collection is identified by a unique Path. Each Collection also has a Title.
Each Collection has its own Field Dictionary.
Each Note in a Collection must have an ID that is unique within that Collection. The ID is formed from one or more Fields within each Note. The Collection specifies the rule for constructing the IDs for all Notes within that Collection.
V
*
Note
A Note is a text-based object containing multiple Fields. At a minimum, a Note consists of a Title Field and a Body Field. A Note may also have one or more Attachments. A Note can only exist as part of a Collection.
V
*
Field
Each Field consists of a Field Definition and a Value.
V
>
Field Label
A Field Label includes a Proper Form and a Common Form.
V
*
Proper Form of a Label
This is the Field Label as it would normally be written or read by a human, using capitalization, spacing and punctuation. The Proper Form of a Field Label may not be longer than 48 characters, and may not contain a comma or a colon.
V
*
Common Form of a Label
This is the Field Label with capitalization, spacing and punctuation removed. It is this form that should be used by the software as the internal key for the associated Field Value.
V
*
Field Value
This is a string of text representing a single piece of information about a Note.
V
*
Field Dictionary
A Field Dictionary contains a Field Definition for each different Field Label used within the Collection.
V
*
Field Definition
The key for each Field Definition comes from the Common Form of its Field Label. In addition to the Field Label, the Field Definition identifies a Field Type.
V
V
Field Type
Identifies certain characteristics for a particular type of Field.
*
Set field type to integer value
*
Get field type as integer value
V
*
Attachment
An Attachment is a file that is attached to a Note. Each Attachment is identified by an optional ID, as well as by its file extension. Each Attachment for a Note must have a combination of ID and file extension that is unique among all Attachments for that Note. Note that the original name and location of the file (before attachment to a Note) are not preserved.
V
V
Field Labels and Field Types
Although Notenik supports any Field Label fitting the constraints given above, it also defines a set of Privileged Field Labels. These Privileged Labels are expected to be commonly used, and each of these Privileged Labels is assumed to have a particular Field Type associated with it.
Although some Field Types support multiple occurrences within them, a particular Field Label cannot be repeated within a Note, or within a Dictionary. On the other hand, some Field Types can be reused within a Note, and within a Dictionary.
A Field Type may sometimes be assumed based on the appearance of a certain word within a Field Label. Any Field Label containing the word 'date', for example, will be assumed to be of the Date Type. Similarly, any Field Label containing the work 'link' will be assumed to be of the Link Type.
For Field Labels that have identically named Field Types, you may assume that the Field Type applies to the Field Label with the same name. For the sake of simplicity and clarity, Field Labels will be listed first, and associated Field Type information will be given under the associated Label, when both Label and Type have the same name.
>
Field Types
*
Recurs
*
Rating
*
People
V
*
Tags
The tags or categories assigned to a Note. A tags field may consist of multiple levels, with the first level being the primary tags and subsequent levels being sub-categories.
V
*
Date
A complete or partial date that can be parsed into a year, month and/or day of month.
V
*
Status
A single digit in the range of 0 - 9, along with a corresponding label.
*
Link
*
Seq
*
Index
V
*
Long Text
A String of any length, that may contain markup. Markdown is the preferred, and presumed, language used for markup.
V
*
Simple String
A relatively short string that is not expected to contain any markup.
>
Privileged Field Labels
V
*
Body
The Body consists of the text of the Note, containing as many words as you like. The Body Field is of the Long Text Type.
V
*
Title
A Title consists of a few words telling you what the Note is about. The Title Field is of the Simple String Type.
V
*
Tags
A tag represents a particular topic or category. One or more tags may be assigned to each Note, and each tag may have sub-tags. All of the tags and sub-tags for a Note are defined within a single Tags Field.
A period or a slash may be used to separate one level of a tag from the next level, with the period being preferred. A comma or a semi-colon may be used to separate one tag from another, with the comma being preferred.
V
>
Status
A Status Field identifies a degree of readiness/completion for a Note.
Status values are usually selected from the following standard list. Note that each status may be represented by a single digit and/or an associated label. The digits serve to place the values into an approximate life cycle sequence.
*
0 - Suggested
*
9 - Deleted: Ready for deletion, or already deleted
*
5 - Held for Later Use, but not currently active
*
3 - Planned
*
4 - Published/Active/In Work
*
2 - Approved
*
1 - Draft/Proposed
*
7 - Canceled: Not completed, and never to be completed
*
6 - Completed: All required actions have been taken
*
8 - Closed/Archived: Only of interest for historical purposes
V
*
Type
The type of note. Any values may be used to distinguish between different types of notes within a collection. The Type Field is of the Simple String Type.
V
*
Link
A Link field contains a URL/hyperlink to a related resource. This may be a link to a resource on the Web, or to a local file, or to another Collection.
V
*
Seq
A Seq field may be used to specify a sequence number, revision letter, or version number.
A Seq field may contain letters, digits and one or more periods (aka decimal points) or hyphens or a dollar sign ('$').
A Seq value may be consistently and systematically incremented, and may be compared to another Seq value for equality or for sequencing.
V
*
Rating
A rating of the note, on a scale of one to five.
V
*
Code
The Code Field is intended to contain a code snippet associated with the Note, using a relevant coding language (HTML, Java, etc.).
A Code Field is of the Long Text Type, although it would be typically displayed in a monospaced font, and without any interpretation of the code found within.
V
*
Author
Identifies the author(s) of the Note, using the People Field Type.
V
*
Date
The Date Field may be used to track a date of some significance. Depending on the nature of the Collection, the Date Field might be used to track a due date, or a date published.
A Date Field is assumed to contain a complete or partial date, represented as a string. If a partial date, then Year, or Year and Month, may be specified without a Day of Month. A Date Field may or may not contain a specific time of day.
V
*
Teaser
An excerpt or summary of the Note that is meant to help readers decide whether they wish to read the full Body. The Teaser Field is of the Long Text Type.
V
*
Index
An Index Field can contain one or more terms under which this Note should appear in an index of the Collection. Multiple terms can be entered by using a semi-colon (‘;’) to end each term entry. A URL to be associated with the term can be placed in parentheses following the term. If the term should reference a specific anchor within the Note, then the anchor can be specified by preceding it with the usual pound sign (‘#’).
V
*
Recurs
A Recurs Field may be used to specify a recurrence rule for the Date Field. The Recurs Value may be specified using normal English, such as "Every 3 months, "Every Tuesday" or "Every Year".
V
>
Software Architecture
The Notenik architecture may be implemented using a variety of technology stacks. Software stacks may be built using varying programming languages, database management systems, and web and application servers. The software architecture should contain the following pieces.
V
*
Data Model
The Data Architecture should be instantiated with a series of Classes representing the various objects and their attributes, along with standard getters and setters. The data model should be platform-neutral (although may be rewritten in different languages).
V
*
I/O Module
An I/O module has responsibility for updates and retrievals to and from a particular data store. The data store could be file-based, or use a relational database, or a NoSQL database.
V
*
Transformers
It should be possible to transform a single Note, or an entire Collection of Notes, into an alternate representation, for various uses. For example, it should be possible to transform a Collection of Notes into a standard tab-delimited or comma-separated file. One or more Transformers may make use of a particular templating system.
V
V
User Interface
A UI should consists of a set of Views and Controllers designed to allow users to interact with the Data Model on a particular device type.
V
*
Controller
Controllers should provide the "glue" that ties together all of the other pieces of the software architecture into a functioning system.
V
*
Views
Widgets and such used to represent the data.