Architecture
Architecture is a document that describes how things work.
What is the goal of architecting before coding?
    Spend more time figuring out how your code will work
    Spend less time writing code
    80% of time architecting, 20% coding
    But really...
    Reduce time spent rewriting code
    Improve code quality and cohesion
    Future-proofing code
Exhibit-1

Process

    1.
    Draft the architecture for the feature using the template
    2.
    Be sure to describe, in as much detail, every section of the template
    3.
    Commit your architecture every day or two
    4.
    Present the architecture to a qualified party
    5.
    Implement the feature
    6.
    Update the architecture as you go, especially the R&D section
    7.
    Update the architecture upon completing your feature
    8.
    Completion date, post-mortem, R&D, etc.
Template
1
# [Feature Title]
2
3
4
## Description
5
This is the general "what?" of the feature. What is your feature? Why is it important? Keep it brief and to-the-point.
6
7
8
## Goals
9
* The "why?" of this feature
10
* Point form
11
* High-level
12
* Not more than 5
13
14
15
## Post-Mortem (optional)
16
Initially TBD. This section is filled after development is complete.
17
18
* Mistakes
19
* This should be updated as you implement the feature
20
* Add anything that you missed in your original architecture
21
* Challenges
22
* This should be updated as you implement the feature
23
* Add anything that was more challenging than expected, and may have contributed to misjudgement of time
24
* Metrics
25
* List the metrics changes that arose after the feature was shipped
26
* Don't forget to compare them with your expectations
27
* Learnings
28
* Jot down what you learned in architecting and building this feature
29
* How will you improve in future feature architectures and implementations?
30
31
32
## Metrics (optional)
33
* Added
34
* Every new metric that will be tracked
35
* Eg. `CONVERSATION_OPENED { isRead }`
36
* Changed
37
* Every metric that be was modified
38
* Eg. `SIGNUP` segmented by `{ type: 'email'|'facebook' }`
39
* Removed
40
* Every removed metric
41
* Eg. `FACEBOOK_SIGNUP`
42
* Expectations
43
* More
44
* Events that you expect to see more of
45
* Less
46
* Events that you expect to see less of
47
48
Example:
49
* Actions
50
* Added
51
* `AUDIO_SEEK`
52
* `AUDIO_PLAY`
53
* `AUDIO_PAUSE`
54
* `AUDIO_FAST_FORWARD`
55
* `AUDIO_REWIND`
56
* `AUDIO_TOGGLE_MUSIC`
57
* `AUDIO_PLAYBACK_DONE`
58
* Expectations
59
* More
60
* SIGNUP > PREMIUM_SUBSCRIBED
61
62
63
## R&D
64
* Problem: Ask every question that you can think of regarding this feature and the challenges involved in implementing it
65
* Describe results you obtained through research and development
66
* What frameworks did you try? Why?
67
* What information did you gather? StackOverflow answers, videos, GitHub comments, etc.
68
* What assumptions did you make? How did they change? Why?
69
* What had to be reverted? Why?
70
* Solution: What was the final solution? Why did you pick it? List any sources.
71
* Problem 2: ...
72
73
Example:
74
* Problem: `react-native-audio-toolkit` does not support audio playback on a locked device on iOS
75
* https://github.com/futurice/react-native-audio-toolkit/blob/master/docs/API.md#player-methods
76
* `react-native-sound` does not support streaming
77
* https://github.com/zmxv/react-native-sound/issues/353
78
* Solution 1: `react-native-track-player`
79
* https://github.com/react-native-kit/react-native-track-player/wiki/Background-Mode
80
* Solution 2: `react-native-video`
81
* https://github.com/react-native-community/react-native-video#audio-mixing
82
* Conclusion: Use `react-native-track-player` since it's better suited for playing long audio files in the background.
83
* Switch to `react-native-video` if something is missing there.
84
85
86
## Flow
87
* This is the "when?" and "where?" of this feature. Detailed user stories are examples of the flow.
88
* This happens first
89
* Then this
90
* And so forth
91
* Go through all scenarios
92
93
94
## Sub-Features
95
[ ] This is the specific "how?" and "what?" of this feature
96
[ ] Break it down
97
[ ] How will you achieve your goals?
98
[ ] Be as specific as possible
99
[ ] Solve all problems before they occur and discover overlappings
100
[ ] These checkboxes are then checked off as you implement the feature
101
[ ] The feature is complete once all checkboxes are checked, meaning nothing should be missing from this list
102
[ ] Once your architecture is merged, these can be moved to your favourite project management system
103
104
Example:
105
[ ] <ConversationsContainer>: A container that will act as the root for the new <Stack>, left of <NotificationsContainer>
106
[ ] bootyUtil
107
[ ] bootyUtil.getSpanks: Get the number of spanks for the given performer
108
[ ] bootyUtil.checkBooty: Checks the provided booty
109
110
111
## Migration (optional)
112
* How will the current architecture be modified to migrate to this new architecture?
113
* What files will be removed?
114
* What functions will be deprecated?
115
* What storage migrations will be performed
116
117
118
## API
119
* Write as much code in here as you can
120
* Function signatures, constants, contract interfaces, etc
121
* Structure sections by filenames
122
* Be sure to alphabetize your api sections
123
124
### [filename/path/here.js]
125
```js
126
/**
127
* Fully document everything. This code is copy-pasteable for when
128
* you begin the implementation phase.
129
* @return {Boolean}
130
*/
131
function yoMama() {}
Copied!

[another/file/path.js]

Here is an example of a changed file:
1
// ...
2
3
/**
4
* This is a new function in an existing file. It is optionally wrapped in `// ...`.
5
* @return {Any}
6
*/
7
function newFunction() {}
8
9
// ...
10
11
const EXISTING_CONSTANT = {
12
13
// ...
14
15
/**
16
* This is a new property. Notice that it is surrounded by `// ...` to show
17
* that it is modifying existing code.
18
* @type {Object}
19
*/
20
myNewProp: {},
21
22
// ...
23
24
}
Copied!

[contract/location/wayback.sol]

Here is an example of a contract interface:
1
contract Wayback {
2
/**
3
* Keep documenting.
4
*/
5
mapping(bytes32 => address) projectToOwner;
6
mapping(bytes32 => address) eventTxHashToApproved;
7
event action(bytes32 projectId, bytes32 metaData);
8
9
function writeEvent(bytes32 projectId, bytes32 metaData) external {}
10
function writeAndApprove(bytes32 projectId, bytes32 metaData, bytes32 eventTxHash, address thirdParty) external {}
11
function sign(bytes32 projectId, bytes32 metaData, bytes32 eventTxHash) external {}
12
}
Copied!
```

Examples

Check here for a description of the examples used below.

Got a comment? Check out our Gitter Channel!
Copyright and related rights waived via CC0
Last modified 2yr ago