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
3.1 KiB
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!