Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Web build context is the repo root. Host node_modules hold macOS native binaries
# that must not replace the Linux ones from npm ci, and .env must not reach an image.
.git
**/node_modules
**/dist
**/.venv
**/__pycache__
**/.pytest_cache
**/.ruff_cache
.env
.env.*
!.env.example
15 changes: 15 additions & 0 deletions .editorconfig
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

[*.py]
indent_size = 4

[{Makefile,Caddyfile}]
indent_style = tab
7 changes: 7 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Copy to .env. On the server, .env lives in DEPLOY_PATH and is never committed.

# Domain for automatic HTTPS, for example app.example.com. Empty means plain HTTP on :80.
SITE_ADDRESS=

# Backend settings (app/config.py). Field names map to upper case env vars.
APP_NAME=junction-2026
141 changes: 141 additions & 0 deletions .github/workflows/ci-cd.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
name: ci-cd

on:
pull_request:
push:
branches: [main]
workflow_dispatch:

concurrency:
group: ci-cd-${{ github.ref }}
# Cancel stale PR runs only. A main run that is cut short could skip a deploy.
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

permissions:
contents: read

jobs:
backend:
runs-on: ubuntu-latest
defaults:
run:
working-directory: backend
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v6
with:
enable-cache: true
- run: uv sync --frozen
- run: uv run ruff check .
- run: uv run ruff format --check .
- run: uv run pytest

frontend:
runs-on: ubuntu-latest
defaults:
run:
working-directory: frontend
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
cache-dependency-path: frontend/package-lock.json
- run: npm ci
- run: npm run typecheck
- run: npm run lint
- run: npm run format:check
- run: npm run build

infra:
runs-on: ubuntu-latest
env:
# Same image as `make check-infra`. actionlint 1.7.12, ships shellcheck.
LINT_IMAGE: rhysd/actionlint@sha256:b1934ee5f1c509618f2508e6eb47ee0d3520686341fec936f3b79331f9315667
steps:
- uses: actions/checkout@v4
- run: docker run --rm -v "$PWD:/repo" -w /repo "$LINT_IMAGE"
- run: docker run --rm -v "$PWD:/repo" -w /repo --entrypoint shellcheck "$LINT_IMAGE" scripts/deploy.sh

images:
if: github.ref == 'refs/heads/main'
needs: [backend, frontend, infra]
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
outputs:
registry: ${{ steps.registry.outputs.name }}
steps:
- uses: actions/checkout@v4

# GHCR rejects upper case, and the owner name may contain it.
- id: registry
run: echo "name=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"

- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}

- uses: docker/setup-buildx-action@v3

- uses: docker/build-push-action@v6
with:
context: backend
push: true
tags: ${{ steps.registry.outputs.name }}/backend:${{ github.sha }}
cache-from: type=gha,scope=backend
cache-to: type=gha,mode=max,scope=backend

- uses: docker/build-push-action@v6
with:
context: .
file: frontend/Dockerfile
push: true
tags: ${{ steps.registry.outputs.name }}/web:${{ github.sha }}
cache-from: type=gha,scope=web
cache-to: type=gha,mode=max,scope=web

deploy:
if: vars.DEPLOY_FROZEN != 'true'
needs: images
runs-on: ubuntu-latest
environment: production
concurrency:
group: deploy-production
# Never stop a deploy half way. The next one waits its turn.
cancel-in-progress: false
permissions:
contents: read
packages: read
steps:
- uses: actions/checkout@v4

- uses: appleboy/scp-action@v0.1.7
with:
host: ${{ secrets.DEPLOY_HOST }}
username: ${{ secrets.DEPLOY_USER }}
key: ${{ secrets.DEPLOY_SSH_KEY }}
source: docker-compose.yml,scripts/deploy.sh
target: ${{ secrets.DEPLOY_PATH }}

- uses: appleboy/ssh-action@v1.2.0
env:
GHCR_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GHCR_USER: ${{ github.actor }}
REGISTRY: ${{ needs.images.outputs.registry }}
TAG: ${{ github.sha }}
DEPLOY_PATH: ${{ secrets.DEPLOY_PATH }}
with:
host: ${{ secrets.DEPLOY_HOST }}
username: ${{ secrets.DEPLOY_USER }}
key: ${{ secrets.DEPLOY_SSH_KEY }}
envs: GHCR_TOKEN,GHCR_USER,REGISTRY,TAG,DEPLOY_PATH
script: |
set -euo pipefail
echo "$GHCR_TOKEN" | docker login ghcr.io -u "$GHCR_USER" --password-stdin
cd "$DEPLOY_PATH"
REGISTRY="$REGISTRY" bash scripts/deploy.sh "$TAG"
25 changes: 25 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Python
__pycache__/
*.py[cod]
.venv/
.pytest_cache/
.ruff_cache/

# Node
node_modules/
dist/
*.tsbuildinfo

# Env and secrets
.env
.env.*
!.env.example

# Deploy state on the server
.last_good_tag

# OS and editors
.DS_Store
.idea/
.vscode/
*.log
98 changes: 98 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# Code Rules

Rules for all code in this repo. Tools enforce some of them. Review checks the rest.

## Enforced by tools

Run `make check` before every push. CI runs the same steps.

| Area | Tool | Rules |
| ---------- | ---------- | ---------------------------------------------------------------------- |
| Python | ruff | Line length 100, `E W F I N B UP SIM RET C90 RUF`, complexity 10 |
| Python | ruff | Type hints (`ANN`), no bool params (`FBT`), no private access (`SLF`) |
| Python | ruff | No `print` left in code (`T20`). Tests may skip type hints |
| Python | pytest | All tests pass. Every route lives under `/api` (`test_routes.py`) |
| TypeScript | tsc | `strict`, no unused locals or parameters, no `enum` |
| TypeScript | oxlint | Warnings fail. No `any`, no `==`, braces always, hook rules |
| TypeScript | oxlint | Named exports only. `fetch` only in `src/api.ts` |
| TypeScript | prettier | No semicolons, single quotes, trailing commas, width 100 |
| Infra | actionlint | Workflow files are valid |
| Infra | shellcheck | `scripts/deploy.sh` passes |
| GitHub | settings | PR with green checks before `main`. Needs a public repo or paid plan |

Review checks the rules below that no tool can check, for example the layers, arrange/act/assert
in tests, and why-comments.

## Clean code

* Use braces on every `if`, `else` and loop, also for one line bodies.
* Split a call, object or parameter list over lines when it has 2 or more items. In Python, add a
trailing comma so ruff keeps the split.
* One statement per line.
* Use early returns. Do not nest conditions deeply.
* Put a blank line between logical blocks (for example call, guard, return).
* Order a file as constants, types, helpers, then main logic.
* Give repeated or meaningful values a named constant. Values from a spec always get a constant
(use `HTTPStatus.OK`, not `200`).
* Do not repeat the same structure more than twice. Extract a helper.

## Comments

* Explain why, not what. If a comment repeats the code, delete it.
* Improve the names before you add a comment.
* Comment non-obvious decisions, workarounds and platform quirks.
* When you fix a bug, say what was wrong and why the fix works.
* A TODO says what to do and when, for example
`# TODO: replace polling with SSE when the stream endpoint exists`.
* Do not commit code that is commented out. Git keeps history.
* A test says why the behavior matters, not only what it checks.
* Use simple English. No em dashes.

## Names

* Names state intent. Prefer a verb for a function (`get_health`, `getHealth`).
* Keep function names under 30 characters.
* Booleans start with `is`, `has`, `should` or `can`.
* Use short names (`i`, `err`) only in small scopes.
* Use an enum or a union type, not a boolean parameter.

## Design

* Keep things private unless another module needs them. Python names start with `_`. TypeScript
does not export what nothing imports.
* Respect the layers. Each layer calls only the layer directly below it.

```
App.tsx (UI) --> src/api.ts --> fetch --> Caddy /api/* --> FastAPI router --> service code
```

* The frontend calls the backend only from `src/api.ts`. Wire values (status strings, field names)
stay in `src/api.ts`. The UI gets domain values.
* Every backend route lives under `/api`. Add routers in `create_app` with `prefix=_API_PREFIX`.
* Do not move or rename `GET /api/health`. The container health check and the deploy rollback
depend on it.
* The backend runs one worker. In memory state must stay in one process.
* No speculative code. Add an interface, config or extension point only when something uses it.
* Handle error paths and edge cases in the same change, not later.

## TypeScript

* `const` by default, `let` only when you reassign. Never `var`.
* No `any`. Use `unknown` and narrow it.
* Named exports only (`vite.config.ts` is the exception, Vite needs a default export).
* `interface` for object shapes, `type` for unions.
* `readonly` for properties that do not change.
* Explicit return types on exported functions.

## Python

* Type hints on every function signature.
* `pathlib.Path`, not `os.path`.
* f-strings, not `%` or `.format()`.
* Tests use arrange, act, assert blocks with a blank line between them.

## Shell

* Quote and brace variables: `"${name}"`.
* Use `[[ ]]`, not `[ ]`.
* Put logic longer than a few lines in a function.
18 changes: 18 additions & 0 deletions Caddyfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# SITE_ADDRESS=example.com gives automatic HTTPS. Default :80 serves plain HTTP for local use.
{$SITE_ADDRESS::80} {
encode gzip

handle /api/* {
# Flush at once so SSE streams are not buffered.
reverse_proxy backend:8000 {
flush_interval -1
}
}

# SPA: unknown paths fall back to index.html for client routing.
handle {
root * /srv
try_files {path} /index.html
file_server
}
}
40 changes: 40 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
.PHONY: setup check check-be check-fe check-infra fmt dev-be dev-fe up down

# Same image as the CI infra job. actionlint 1.7.12, ships shellcheck.
LINT_IMAGE := rhysd/actionlint@sha256:b1934ee5f1c509618f2508e6eb47ee0d3520686341fec936f3b79331f9315667
LINT_RUN := docker run --rm -v "$(CURDIR):/repo" -w /repo

# Install all deps for local work.
setup:
cd backend && uv sync
cd frontend && npm ci

# Same steps as CI. Run before every push.
check: check-be check-fe check-infra

check-be:
cd backend && uv run ruff check . && uv run ruff format --check . && uv run pytest

check-fe:
cd frontend && npm run typecheck && npm run lint && npm run format:check && npm run build

check-infra:
$(LINT_RUN) $(LINT_IMAGE)
$(LINT_RUN) --entrypoint shellcheck $(LINT_IMAGE) scripts/deploy.sh

fmt:
cd backend && uv run ruff check --fix . && uv run ruff format .
cd frontend && npm run format

dev-be:
cd backend && uv run uvicorn app.main:app --reload --port 8000

dev-fe:
cd frontend && npm run dev

# Full stack as in prod, built locally. http://localhost
up:
docker compose up -d --build --wait

down:
docker compose down
Loading
Loading