Skip to content

Commit 793f7e0

Browse files
mykhailodanilenkomykhailodanilenko
authored
Merge pull request #85 from mykhailodanilenko/feature/docs-setup
Setup documentation
2 parents 43c86b2 + e1d2738 commit 793f7e0

File tree

4 files changed

+143
-0
lines changed

4 files changed

+143
-0
lines changed

‎README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,7 @@ When a improvement is ready to be contributed in a pull request, please review t
3333
4. Ensure that the changes adhere to the project code style and formatting rules by running `npx eslint .` and `npx prettier --check ../` from the `./OwnTube.tv/` directory (without errors/warnings)
3434
5. Include links and illustrations in your pull request to make it easy to review
3535
6. Request a review by @ar9708, @OGTor, @tryklick and @mblomdahl
36+
37+
## Documentation
38+
39+
Refer to [documentation](docs/index.md) for additional info.

‎docs/index.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
### Introduction ###
2+
3+
This is an overview of the OwnTube.tv client, specifically the frontend part of it. This document will guide you through
4+
the [project folder structure](structure.md), [the technologies used](tech.md), reasoning behind some of the decisions made.

‎docs/structure.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
## Folder structure
2+
3+
For convenience, we will consider all folder names prefixed by `./OwnTube.tv/`
4+
5+
### 📁`/__mocks__/`:
6+
7+
This is a utility folder where you can put mocks for modules that you are sure will be used in all tests across the app.
8+
9+
File structure: `/__mocks__/<moduleName>/<fileToMockName>.js`
10+
11+
This is quite handy for react-native projects as some native modules will never render in a test renderer (e.g. *Camera*).
12+
Some libraries have instructions for creating such mock files.
13+
14+
Alternative: 1 large `jest.setup.js` file with all the mocks.
15+
16+
### 📁`/api/`:
17+
18+
The 2 base structures working with the PeerTube API are contained in `peertubeVideosApi.ts` and `queries.ts`.
19+
20+
`peertubeVideosApi.ts` contains the Axios instance and data fetching methods. There are predefined base query params and logic for response transformation.
21+
However please note that the instance URL is obtained from request params to support choosing the peertube instance to fetch from.
22+
23+
`queries.ts` contains React hooks that wrap around the data fetching functions and handle things like loading state, refetching, cache invalidation through the use of `tanstack-query` (formerly `react-query`) library.
24+
25+
The tests covering these files can be found in the `/api/tests/` folder.
26+
27+
### 📁`/app/`:
28+
29+
This directory's structure is static and determined by the `expo-router` package guidelines.
30+
More insight on why expo-router is used can be found further in the document, and more information on the file structure can be found here: https://docs.expo.dev/router/create-pages/
31+
32+
The route structure is as follows:
33+
34+
`(home)/<screen>` where `(home)` is the base path and the 2 available screens - `/settings` and `/video` are separate routes.
35+
There is also a file for the `(home)/index` route which corresponds to the home page (`/`).
36+
37+
Each route has a `backend` parameter and the `/video` route additionally has `id` and `timestamp` params used for video playback.
38+
All the routes come together in the `_layout.tsx` file which exports the app navigation.
39+
The reasoning behind the inclusion of the `+html.tsx` file will be discussed further in the document.
40+
41+
### 📁`/assets/`:
42+
43+
Contains logos and test data jsons, only the files put in this folder will be included in the build.
44+
45+
### 📁`/components/`:
46+
47+
A base folder for React components used in the app, the `/shared/` folder contains base component like "button" or "spacer".
48+
Some of the components that require a lot of supporting files (styles, tests etc.) are placed in a single folder,
49+
while most consist of 1 file which contains the styles (if any) and the component code.
50+
51+
### 📁`/contexts/`:
52+
53+
This folder contains setup files for information that should be available across the whole app - one is a color context used
54+
for theme switching and the other is the `AppConfigContext` which is used for technical information like settings or
55+
device capability info.
56+
57+
### 📁`/hooks/`:
58+
59+
Each file in this folder contains a React hook and if available, a file with the same name with a `.test.ts` extension.
60+
61+
### 📁`/layouts/`:
62+
63+
Contains layout components, currently having only one - a `<Screen />` that wraps app screens.
64+
65+
### 📁`/patches/`:
66+
67+
Contains patches used by the `patch-package` package. Best to keep this folder temporary.
68+
69+
### 📁`/screens/`:
70+
71+
This folder contains screen components which are imported into the route files in the `/app/` folder. Mostly these screens
72+
consist of components from the `/components/` folder.
73+
74+
### 📁`/theme/`:
75+
76+
Contains stylistic values and variables, such as colors or typography, however currently the app is mostly using the built-ins from `react-navigation` (a dependency of `expo-router`)
77+
78+
### 📁`/utils/`:
79+
80+
Here you can find various utilities used across the app, such as time formatting or working with async storage, test setup helpers etc.

‎docs/tech.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
## Technologies used
2+
3+
### Framework 🖼️
4+
5+
This app uses Expo which is a framework of React Native which simplifies the DX drastically for a lot of use cases.
6+
7+
### Data Fetching ⬇️
8+
9+
The project uses `tanstack-query` library for its simplified data handling, automatic background refetching, and performance optimization
10+
through built-in caching. Its powerful DevTools and flexibility in supporting various use cases enhance our development
11+
efficiency, while an active community ensures we stay updated with the best practices.
12+
13+
### Navigation 🧭
14+
15+
A significant majority of React Native projects use the `react-navigation` navigation library. This project, however, uses
16+
a file-based routing solution built on top of it by Expo, called `expo-router`. Expo-router comes with some additional features,
17+
such as deploying your application on the web in 3 different ways ('static', 'single' and 'server').
18+
19+
The 'static' export is what allows us to deploy the app to GitHub pages as a set of html files (hence the name "static").
20+
This allows us to refresh the page without 404 errors unlike a "single" export (which would be the only option if we didn't use `expo-router`).
21+
However, there is currently a problem that comes up when deploying the app to GH Pages, which was patched in the `/patches/` folder. Currently, an issue
22+
in the Expo Github repo is created and assigned to a team member there.
23+
24+
Each page is navigated to with a `backend` param so that the chosen instance link is determined by the URL and not the internal memory state.
25+
For example, if the user has `foo.bar` chosen in settings and gets a link to `owntube.tv/video?backend=bar.baz&id=123`, then they will watch a video from `bar.baz` that they were sent.
26+
27+
The video page also has params such as `id` (the video uuid) and `timestamp` (the time when we want the video to start from when the link is opened)
28+
29+
The settings page has only the `backend` param and uses it to show the currently selected instance, when the user select a new one they are "navigated" to the same page with a different `backend` param.
30+
31+
### Video playback 📼
32+
33+
The turnkey solution for Expo apps is expo-video. However, this library is still in beta state and is considered unsupported
34+
on TV devices. So, the OwnTube.tv client uses an older `expo-av` library.
35+
36+
A PeerTube instance outputs two variants when a video is fetched - either an mp4 video file, or an HLS streaming playlist,
37+
or both. However, not all videos have both, so we need to be able to play both variants.
38+
39+
HLS is a technology which is not supported natively on desktop browsers except for Safari. Thus, we need a custom solution to support Chrome and FF.
40+
The `video.js` library includes the `hls.js` library which is used by PeerTube on the frontend in their custom peer-to-peer loader. However this custom loader is not
41+
necessary for the current needs of OwnTube.tv.
42+
In our case, a platform-specific component is used for the Web platform (React Native is able to determine where it is running and will supply the specific component).
43+
Through video.js we are converting the hls stream into a stream of mp4 chunks which are readable in any browser on the fly using ffmpeg, thus enabling the hls playback.
44+
45+
The video controls are overlaid above the video player, this way the experience is unified regardless of the platform.
46+
You can skip 10 seconds in each direction, seek through the video, play/pause, mute.
47+
48+
### Testing
49+
50+
Jest is used throughout the app for testing, both for component tests and unit tests. For testing React components, the
51+
`@testing-library/react-native` package is used, which allows us to test components as real functioning entities,
52+
with state changes, user interactions etc. which in turn allows us to write tests similar to integration tests (e.g. user
53+
clicks X button and sees Y result).
54+
55+
Data fetching is tested against a real peertube nightly instance, without mocking the API response.

0 commit comments

Comments
 (0)