mirror of
https://github.com/zkldi/Tachi.git
synced 2026-09-26 00:47:57 +03:00
zk
e363bd2532
* docs: migrate from mkdocs to mdbook - Rename old mkdocs docs/ to old-docs/ for reference - Set up new docs/ with mdbook (book.toml + src/ tree) - Mirror full nav structure from mkdocs.yml into SUMMARY.md - Add Justfile-docs with docs-serve, docs-build, docs-check, docs-install recipes - Import Justfile-docs from root Justfile - Rewrite .github/workflows/docs.yml: build step uses taiki-e/install-action to install mdbook, split into separate build + deploy jobs, PR builds run the check step too * ci(docs): pin actions to SHAs, install mdbook via release binary * ci(docs): install mdbook from apt instead of curling a release binary * dev: replace mkdocs python stack with mdbook in dev image * ci(docs): apt only works on Debian; restore release binary install for Ubuntu CI * docs: fix duplicate file entries in SUMMARY.md * docs: remove docs-install recipe * docs: remove site-url from book.toml to fix asset loading * dev: install mdbook from upstream release binary, not Debian apt The Debian package (0.4.x+ds) strips bundled font assets, leaving the built site without fonts/fonts.css. Use the upstream tarball (same as CI) so the theme is complete. Handles x86_64 and aarch64. * docs: vendor mdbook tarballs in dev/mdbook/, install from there Dockerfile.dev uses COPY + tar to install the right arch at build time. CI extracts the x86_64 tarball directly from the checkout. No network access required for either — and no stripped-fonts Debian package. * fix: unwritten
131 lines
3.1 KiB
Markdown
131 lines
3.1 KiB
Markdown
# File/Folder Organisation
|
|
|
|
`tachi-server` has a specific setup of files and folders
|
|
to ensure that code is at where it's most sensible.
|
|
|
|
!!! note
|
|
This documentation is a rough guide for where
|
|
to place files if you are writing a new file,
|
|
or where to look for certain functionality.
|
|
|
|
It is not a comprehensive tutorial for every file
|
|
in the repo, as that would be a pain to keep updated.
|
|
|
|
*****
|
|
|
|
## Top Level
|
|
|
|
All of these are at the root level of the project.
|
|
|
|
### `/src`
|
|
|
|
All of the server TypeScript code goes here.
|
|
|
|
### `/js`
|
|
|
|
!!! info
|
|
This folder is gitignored.
|
|
|
|
When compiled, `tsc` will output the JS code here.
|
|
|
|
### `/scripts`
|
|
|
|
Various scripts for interacting with `tachi-server`, such
|
|
as single-use scripts for importing some data, or
|
|
frequently used scripts such as updating BMS tables.
|
|
|
|
## TypeScript Source Code
|
|
|
|
All of these are inside `/src`.
|
|
|
|
### `/datasets`
|
|
|
|
Some of `tachi-server`'s code interacts with datasets that
|
|
aren't worth putting into MongoDB, such as splash text.
|
|
|
|
This is mainly for things where we want to randomly select
|
|
from the list, and not perform any serious lookups - which
|
|
is why it's a good fit for splash text/automatic session names.
|
|
|
|
!!! info
|
|
Selecting a random element from an entire collection
|
|
in MongoDB is relatively expensive, and would quadruple
|
|
the time an import takes.
|
|
|
|
!!! warning
|
|
TypeScript does not support copying over non-code files.
|
|
|
|
You can use `cp` in post to move files around, or
|
|
place the data in memory, either is fine.
|
|
|
|
### `/external`
|
|
|
|
Code relating to the "external" applications for `tachi-server`,
|
|
such as MongoDB and Redis.
|
|
|
|
### `/lib`
|
|
|
|
Sets of code for `tachi-server` functionality. This is the
|
|
main important part of the codebase for handling things
|
|
like score imports, logging, and more.
|
|
|
|
### `/server`
|
|
|
|
This contains the express application that `tachi-server`
|
|
uses in order to be a server.
|
|
|
|
This contains our API, IR implementations and a way of
|
|
serving our PWA.
|
|
|
|
### `/test-utils`
|
|
|
|
Tachi's tests need mocks and some specialised code in order
|
|
to work well. This folder contains all of those things.
|
|
|
|
!!! warning
|
|
**NOTHING** from this folder should be ran in production.
|
|
|
|
### `/utils`
|
|
|
|
Small utilities for interacting with Tachi, such as
|
|
functions that retrieve a user given certain params.
|
|
|
|
This also contains utilities for handling song/chart
|
|
database lookups - such as looking up on BMS hash.
|
|
|
|
## Express Server
|
|
|
|
All of the below folders are under `/src/server`.
|
|
|
|
As mentioned above, Tachi stores the routing for our
|
|
APIs and IR implementations here.
|
|
|
|
### `/middleware`
|
|
|
|
This contains the middleware we use for the server,
|
|
such as authentication middleware and such.
|
|
|
|
### `/router`
|
|
|
|
This contains the actual 'routes' for our server.
|
|
|
|
The folders here **MUST** be 1:1 with the endpoints
|
|
on the server. For example, the implementation of
|
|
|
|
```
|
|
https://boku.tachi.ac/api/v1/foo/bar
|
|
```
|
|
|
|
**MUST** be found at `src/server/router/api/v1/foo/bar/router.ts`
|
|
|
|
### Router Files
|
|
|
|
The only files allowed to declare endpoints are `router.ts` files.
|
|
|
|
This allows us to separate functionality from API structure
|
|
in cases where an API call needs to do a lot of things.
|
|
|
|
## Test Files
|
|
|
|
This documentation has been moved to [its own page](./testing.md)!
|