Start here
Read this when you are new to the repository or need to find the right page for a task.
Tadoku is a foreign-language immersion tracker and contest platform. Learners log reading and listening, join contests with registration windows and compare scores on leaderboards. This site documents how the software is built, run in the development environment and verified.
Repository map
| Path | Contains |
|---|---|
services/ | Go services built with Bazel: tadoku-api (the only backend), supporting services and shared packages in services/common/ |
frontend/ | pnpm workspace: webv2, webv3, authv2 and admin, the styleguides and Paper playground, and the ui and paper-ui design systems |
docs/ | This Docusaurus site; pages live in docs/docs/ |
k8s/ | Development-only GitOps base for Argo CD in k8s/dev/base/ |
infra/ | A development kubeconfig helper |
scripts/ | Code generation, the Tadoku API visibility check, and development seed and secret bootstrap scripts |
tools/ | CI check scripts and the pinned oapi-codegen module |
.dev/ | dev-cli configuration, deployable definitions and the development runbook |
.agents/ | Repository dev-cli and verify-tadoku agent skills |
Where to go
| Task | Page |
|---|---|
| Install tools, build, test and run code generators | Toolchain and repository |
| Run your branch against the shared development environment | Development environment |
| Prove a change works and publish evidence | Verifying changes |
| Deploy or verify a branch beside production | Production branches |
| Commit, open a pull request, ship a migration or report a bug | Contributing workflow |
| Understand the running system and request paths | System overview |
| Design or review a module boundary or shared abstraction | Module design |
| Use or design a concern that many features share | Cross-cutting concerns |
| Work with sign-in, roles and bans | Authentication and authorization |
| Define a feature's permissions, or write, read or check relationships | Permission model |
| Call one service from another | Service-to-service auth |
| Gate behavior behind a flag | Feature flags |
| Read past design decisions | Decisions |
| Change backend behavior | Tadoku API |
| Change the database schema or a query | Tadoku API database |
| Write or lay out Go code | Go style |
| Write backend tests | Tadoku API testing |
| Change a frontend application | Frontend overview |
| Build a Paper screen | Paper composition |
| Operate the development base or repair data | Operations |
| Look up a public endpoint | API reference |
For agents
AGENTS.mdat the repository root is the entry point. It holds the rules for every change and names the page that holds each area's rules.- Every page has a one-sentence
descriptionin its frontmatter and opens with a "Read this when …" line, so you can choose pages without reading them fully. - Repository paths are written as inline code relative to the repository root,
for example
services/tadoku-api/spec/openapi.yaml. - Without a checkout, start from
llms.txton the published site; it lists every page with its description and source file.