Tomoda Engineering

Tomoda is a location-based social event platform. This site documents how it's built, how to run it, and how it ships to production.

How to read these docs

These docs are organized as a layered map of the platform. The Architecture section is the entry point for cross-cutting design — how authentication flows, how real-time chat is wired, how the data model is shaped, and what the bounded domains are. Read it before diving into a specific subsystem; everything else assumes you have that mental model.

The remaining sections each zoom in on one slice of the stack. Backend and Frontend cover the two services in depth — internal architecture, conventions, and how individual modules fit together. Style Guide is the visual language — colors, typography, components, brand. Infrastructure is the app's view of the deploy pipeline (local Docker stack, Cloud Build CI, secrets). Operations is the day-to-day toolkit — runbook for incidents, native (iOS + Android) workflow, testing strategy. Reference is the lookup table you reach for mid-task. DevOps is the companion site for everything cluster-side (Terraform, K8s manifests, Argo CD, Postgres operations) — same engineering team, separate repo.

• Architecture
  Cross-cutting system design — auth, real-time, data model, decisions.
  → Architecture

• Backend
  Go service: services, infrastructure, API, security.
  → Backend

• Frontend
  Expo + React Native app: routing, state, components.
  → Frontend

• Style Guide
  Visual language — colors with swatches, typography, components, brand.
  → Style Guide

• Infrastructure
  Local stack, Cloud Build CI, deploy flow, secrets — the app's view.
  → Infrastructure

• Operations
  Runbook, native (iOS + Android) workflow, testing strategy.
  → Operations

• Reference
  Redis keys, env vars, scripts, glossary.
  → Reference

• DevOps
  Cluster-side: Terraform, K8s manifests, Argo CD, Postgres ops.
  → DevOps

Quick links

• Setup — Backend setup for the Go API, Frontend setup for the Expo app
• Native apps — iOS + Android workflow for builds and store releases
• Style — Brand for design principles, Color for live swatches
• Deploy — Deployment for the app's view, DevOps → Deploy for the cluster-side runbook
• Testing — Testing for unit, integration, and E2E
• Lookup — Environment variables, Redis keys, Glossary

Contributing to docs

These docs live in the docs/ directory of the main tomoda repo. To preview locally:

task docs:install   # one-time: installs MkDocs Material into a venv
task docs           # serves at http://localhost:8000 with live reload

PRs are welcome. Keep pages focused — one concept per file, link liberally. Code references should point at real paths in the repo (e.g. backend/internal/services/chat_service.go) — the build-time hook auto-links them to GitHub. Prefer admonitions (!!! note, !!! warning, !!! tip, !!! danger) over bolded inline asides for callouts.