logand.app

Personal + professional site and protected admin tool for Logan Dapp (logand.app / logandapp.com). Public landing/projects/contact pages plus an internal invoicing, budget, and inventory system behind auth -- including multi-method invoice payments (Stripe, PayPal, and manually- recorded Zelle/in-person payments), professional PDF invoice generation, bill-of-materials cost breakdowns tied to inventory consumption, and row-level-locked payment operations so the same invoice can never be double-charged or double-recorded under concurrent requests. A generic, audit-logged admin data browser and centralized, rotating application logging (backend, frontend, and the Android client) round out the operational side -- see docs/design/15-admin-tools-and-observability.md.

Full product spec and architecture: docs/design/ -- start there, not here, for anything about what to build or why. Deploying this yourself? Start at docs/deployment.md instead. Using the deployed site? See docs/usage.md. Already running it and something needs day-2 attention -- a deploy, a migration, mail, an Android release, payments? See docs/OPERATIONS.md. This file only covers how to run the repo. See docs/README.md for the full documentation index.

Layout

backend/      Python / FastAPI / pydantic / typani -- see docs/design/01
frontend/     TypeScript / React / Tailwind -- see docs/design/07
wasm-ascii/   Rust crate, ASCII rasterizer -- see docs/design/08
android/      Kotlin / Jetpack Compose mobile client -- see android/README.md
ops/          VPS-side tooling (backups, release-watch) -- see below
docs/design/  pre-implementation specs, read by component
docs/         deployment/secrets/usage guides + runbooks -- see docs/README.md
.github/      CI (every PR) + deploy (push to main)

Each of backend/, frontend/, wasm-ascii/, android/ is independently buildable via its own Makefile. The root Makefile composes them. android/ is not part of CI (see CI/CD below) and has its own build requirements (JDK 17, Android SDK) -- see android/README.md before running make install/ make test if you don't already have those.

Quick start

docker compose -f docker-compose.dev.yml up -d   # postgres + redis only
cp backend/.env.example backend/.env              # fill in real values, never commit
make install
make migrate -C backend                            # or: make -C backend migrate
make check                                          # lint + typecheck + tests, every subproject

Backend dev server: cd backend && uv run logand-backend (or your IDE's run config against src/logand_backend/__main__.py). Frontend dev server: cd frontend && npm run dev.

Testing

make test runs unit + integration for every subproject. make test-system brings up docker-compose.test.yml and runs the full end-to-end suite (backend httpx system tests + Playwright). Every component is required to carry all three layers -- see docs/design/12-testing-strategy.md for what belongs in which layer before adding a test.

CI/CD

• .github/workflows/ci.yml -- runs on every PR and push to main: lint + typecheck + unit/integration per subproject, then a combined system-test job against docker-compose.test.yml. android/ is not part of this workflow (it's exercised by release-android.yml instead, below) -- run make -C android test (or root make test, which now includes it) locally before pushing android changes.
• .github/workflows/release-android.yml -- on pushing a vX.Y.Z tag: runs :core/:app tests on a real GitHub-hosted (x86_64) runner -- none of android/README.md's aarch64-Linux aapt2 workarounds are needed there -- then, only if tests pass, builds a debug-signed APK (no release keystore exists for this project) and attaches it to a new GitHub Release. See android/README.md for install steps on a real device.
• .github/workflows/deploy.yml -- on push to main, after CI passes: builds images, pushes to GHCR, ships the frontend build + restarts the backend on the VPS over SSH.
• ops/release_watch/ -- a small pull-based fallback: a systemd timer on the VPS polls the GitHub releases API and redeploys if it's behind the latest tag, in case a push deploy fails partway. Not a replacement for deploy.yml, a safety net for it.

Secrets

Never commit .env. Real values go in backend/.env (gitignored) and in GitHub Actions repo secrets. No agent working in this repo should ever read .env directly or indirectly -- see docs/design/00-overview.md and docs/design/02-auth-and-security.md. For what every individual secret is and how to rotate it, see docs/secrets.md.

License

MIT -- use, modify, and redistribute freely, with attribution (see the license file for the exact terms). This is a personal project shared in case any of it (the ASCII renderer, the LaTeX invoice PDFs, the payment-provider abstraction) is useful to someone else, not a maintained product -- expect to fork and adapt rather than file issues against it.