1# Internal architecture
2
3This documentation only provides a bird's-eye view of git-bug's internals. For
4more details, you should read the other documentation and the various
5comment/documentation scattered in the codebase.
6
7## Overview
8
9```
10 .--------------.
11 | | webui | |
12 | '--------------' |
13 | .---------------..-----------..------------..--------------. |
14 | | commands || bridge || termui || graphql | |
15 | '---------------''-----------''------------''--------------' |
16 | .----------------------------------------------------------. |
17 | | cache | |
18 | |----------------------------------------------------------| |
19 | | BugCache,BugExcerpt,IdentityCache,IdentityExcerpt | |
20 | '----------------------------------------------------------' |
21 | .-----------------------------..---------------------------. |
22 | | bug || identity | |
23 | |-----------------------------||---------------------------| |
24 | | Bug,Operation,Snapshot || Identity,Version | |
25 | '-----------------------------''---------------------------' |
26 | .----------------------------------------------------------. |
27 v | repository | v
28 '----------------------------------------------------------'
29```
30
31Here is the internal architecture of git-bug. As you can see, it's a layered
32architecture.
33
34As a general rule of thumb, each layer uses the directly underlying layer to
35access and interact with the data. As an example, the `commands` package will
36not directly use the `bug` or `repository` package. It will request the data
37from the `cache` layer and go from there. Of course, the `commands` package will
38ultimately use types defined in the lower level package like `Bug`, but
39retrieving and changing the data has to go through the `cache` layer to ensure
40that bugs are properly deduplicated in memory.
41
42## repository
43
44The package `repository` implement the interaction with the git repository on
45disk.
46
47A series of interfaces (`RepoCommon`, `Repo` and `ClockedRepo`) define
48convenient for our usage access and manipulation methods for the data stored in
49git.
50
51Those interfaces are implemented by `GitRepo` as well as a mock for testing.
52
53## identity
54
55The package `entities/identity` contains the identity data model and the related
56low-level functions.
57
58In particular, this package contains:
59
60- `Identity`, the fully-featured identity, holding a series of `Version` stored
61 in its dedicated structure in git
62- `Bare`, the simple legacy identity, stored directly in a bug `Operation`
63
64## bug
65
66The package `entities/bug` contains the bug data model and the related low-level
67functions.
68
69In particular, this package contains:
70
71- `Operation`, the interface to fulfill for an edit operation of a Bug
72- `OpBase`, implementing the common code for all operations
73- `OperationPack`, an array of `Operation`
74- `Bug`, holding all the data of a bug
75- `OperationIterator`, allowing to easily iterate over the operation of a bug
76- all the existing operations (Create, AddComment, SetTitle ...)
77- `Snapshot`, holding a compiled version of a bug
78
79## cache
80
81The package `cache` implements a caching layer on top of the low-level `bug` and
82`identity`package to provide efficient querying, filtering, sorting.
83
84This cache main function is to provide some guarantee and features for the upper
85layers:
86
871. After being loaded, a Bug is kept in memory in the cache, allowing for fast
88 access later.
892. The cache maintain in memory and on disk a pre-digested excerpt for each bug,
90 allowing for fast querying the whole set of bugs without having to load them
91 individually.
923. The cache guarantee that a single instance of a Bug is loaded at once,
93 avoiding loss of data that we could have with multiple copies in the same
94 process.
954. The same way, the cache maintain in memory a single copy of the loaded
96 identities.
97
98The cache also protect the on-disk data by locking the git repository for its
99own usage, by writing a lock file. Of course, normal git operations are not
100affected, only git-bug related one.
101
102In particular, this package contains:
103
104- `BugCache`, wrapping a `Bug` in a cached version in memory, maintaining
105 efficiently a `Snapshot` and providing a simplified API
106- `BugExcerpt`, holding a small subset of data for each bug, allowing for a very
107 fast indexing, filtering, sorting and querying
108- `IdentityCache`, wrapping an `Identity` in a cached version in memory and
109 providing a simplified API
110- `IdentityExcerpt`, holding a small subset of data for each identity, allowing
111 for a very fast indexing, filtering, sorting and querying.
112- `Query` and a series of `Filter` to implement the query language
113
114## commands
115
116The package `commands` contains all the CLI commands and subcommands,
117implemented with the [cobra](https://github.com/spf13/cobra) library. Thanks to
118this library, bash and zsh completion, manpages and markdown documentation are
119automatically generated.
120
121## termui
122
123The package `termui` contains the interactive terminal user interface,
124implemented with the [gocui](https://github.com/jroimartin/gocui) library.
125
126## graphql
127
128The package `graphql` implement the GraphQL API, mapping the data model and
129providing read/write access from outside the process. This API is in particular
130used by the webUI but could be used to implement other user interfaces or
131bridges with other systems.
132
133## webui
134
135The package `webui` hold the web based user interface, implemented in both go
136and javascript.
137
138The javascript code is compiled and packaged inside the go binary, allowing for
139a single file distribution of git-bug.
140
141When the webUI is started from the CLI command, a localhost HTTP server is
142started to serve the webUI resources (html, js, css), as well as the GraphQL
143API. When the webUI is loaded in the browser, it interacts with the git-bug
144process through the GraphQL API to load and edit bugs.
145
146## bridge
147
148The package `bridge` contains the various bridge implementation with other
149external bug trackers.