This is a Taito project: a full-stack app whose local development, infrastructure, and CI/CD are all driven by Taito CLI and configured through taito-config.sh and the scripts/ directory.
The real documentation is in docs/ — this file is only an index. Start at docs/development.md.
Reusable, repository-local AI guidance lives in .agents/skills/<skill-name>/SKILL.md. Before changing an area that has a matching skill, read that skill and the referenced documentation. Keep skills generic and grounded in this repository's actual paths, commands, and architecture; application-specific vocabulary, credentials, and external-account procedures belong in the consuming application's documentation instead.
When adding a skill, use a lowercase hyphenated directory name and a concise SKILL.md with YAML name and description. Put stable, detailed guidance in docs/ and link to it from the skill rather than duplicating it. Do not add generated output, credentials, or customer/domain policy to template skills.
| Path | What it is |
|---|---|
client/ |
React + Vite SPA. TanStack Router, Panda CSS, Lingui i18n, gql.tada for GraphQL. |
server/ |
Node/TypeScript API. Domain-driven src/<domain>/*.{resolver,service,dao,db}.ts, setup/ for boot code, db/ for the Drizzle client, migrations and seeds. |
worker/ |
Background job worker; reads jobs from Redis. |
shared/ |
Code and the GraphQL schema shared into every container (symlinked as <container>/shared). |
database/ |
db.sql init script and data/*.sql seed dumps imported on taito init. |
playwright/ |
End-to-end tests. |
storage/ |
Local Minio bucket contents (S3-compatible object storage). |
scripts/ |
Taito CLI configuration, Helm and Terraform definitions. |
docs/ |
Documentation. |
alternatives/ |
Swap-in implementations of client/server in other stacks (Vue, Django, Flask, Micronaut, Remix, Symfony). Not built by default. |
Local containers (taito_containers in scripts/taito/project.sh): client, server, worker, database, redis, storage, pgweb, plus an nginx ingress fronting everything at http://localhost:9999.
Starting, stopping, logs, shells, database access and tests all go through Taito CLI — read .agents/skills/taito-local/SKILL.md before running any taito command, and always use an explicit :local target. docs/development.md has the full command reference.
Database migrations are Drizzle: edit server/src/<domain>/<entity>.db.ts, generate a migration with npm run db:migrate:generate in server/, apply it with taito exec:server:local npm run db:migrate. Details in docs/database/migration.md.
Config is bash variables sourced from taito-config.sh: scripts/taito/config/main.sh derives most taito_* and db_database_* values from scripts/taito/config/defaults.sh (zone/organisation defaults) and scripts/taito/defaults.sh (project identity). Project-specific settings you edit are scripts/taito/project.sh and the per-environment scripts/taito/env-*.sh. taito config:local prints the resolved values — the fastest way to find where a variable comes from.
taito_target_env is the actual environment (local, dev, pr-123, canary, prod); taito_env is the resource environment it maps to — PR environments reuse dev resources, canary reuses prod resources.
Secrets are declared as name:method pairs in scripts/taito/project.sh, mapped to container env vars or files in docker-compose.yaml (local), scripts/helm.yaml (Kubernetes) and scripts/terraform.yaml (serverless), and given values per environment with taito secret rotate:ENV. Local values are gitignored files under secrets/local/; remote values live in the cloud secret store. The full method list and the checklist for adding one are in docs/cli/configuration.md.
Containers are deployed with Helm, other cloud resources with Terraform. Both are configured through cloud-agnostic YAML that is envsubst-ed with the taito config variables before use:
scripts/helm.yaml— services, ingress paths, env vars, secrets, resources, replicas, cron jobs.scripts/helm-<env>.yamlandscripts/helm-<label>.yamloverride it per environment or PR label. Deployed bytaito deployment deploy:ENV.scripts/terraform.yaml(+terraform-<env>.yaml) — databases, buckets, queues, service accounts. Applied manually withtaito env apply:ENV; CI/CD does not apply Terraform changes.
scripts/helm/ is only a wrapper chart — its requirements.yaml pulls the shared full-stack chart from https://taitounited.github.io/taito-charts/, which is where the actual Kubernetes templates live. If a helm.yaml key looks undocumented, look it up in the taito-charts repo, or in the local reference copies scripts/helm/values.yaml and scripts/helm/examples.yaml. Bump the version in requirements.yaml to pick up chart changes.
Files under scripts/helm/, scripts/terraform/ and scripts/taito/config/ are reusable and get overwritten by taito project upgrade — configure things in the *.yaml / *.sh files above them instead. docs/cli/infrastructure.md explains the split.
Branch equals environment: pushing to dev deploys dev, and fast-forward merges to test/uat/stag/canary/master deploy those. Pull requests get a pr-N environment that reuses dev resources with its own database.
The pipeline (cloudbuild.yaml, .github/workflows/pipeline.yaml, or whichever provider's file this project uses) runs a fixed sequence of Taito CLI commands inside the Taito CLI container image: build-prepare → artifact-prepare:<target> → db-deploy → deployment-deploy → deployment-wait → test → deployment-verify → artifact-release:<target> → build-release. Images are tagged with the commit SHA at prepare time and only re-tagged as released after the deployment verifies. Cloud credentials come from CI secrets, optionally prefixed by branch name. taito ci run:dev runs the pipeline locally.
Development happens on dev and feature/*, hotfixes on hotfix/*; a husky pre-commit hook blocks direct commits to environment branches and a commit-msg hook enforces Conventional Commits. semantic-release derives the production version and release notes from them. Run the relevant npm run verify command before handoff; linting and formatting use oxlint / oxfmt.
docs/development.md— prerequisites, quick start, commands, deployment, upgradingdocs/cli/configuration.md— secrets, adding services/databases/buckets, scheduled jobs, object storagedocs/cli/infrastructure.md— what lives underscripts/docs/database/— migrations, seeding, operationsdocs/client/,docs/server/,docs/testing/— per-container guidestaito -h,taito COMMAND -h,taito trouble