Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
ce63734
docs: design repository hardening work
hmmhmmhm Jul 12, 2026
8a51602
docs: plan metrics docs and CI hardening
hmmhmmhm Jul 12, 2026
61f3f53
test(smoke): define isolate metrics contract
hmmhmmhm Jul 12, 2026
51efbcb
fix(smoke): respect Worker isolate metrics
hmmhmmhm Jul 12, 2026
9fedff6
docs: align production and language status
hmmhmmhm Jul 12, 2026
7a71846
ci: enforce repository quality gates
hmmhmmhm Jul 12, 2026
e5d7f79
style: format repository sources
hmmhmmhm Jul 12, 2026
96eede5
docs: plan source size enforcement
hmmhmmhm Jul 12, 2026
238a4bc
test: define source size policy
hmmhmmhm Jul 12, 2026
0231f0e
chore: report oversized maintained sources
hmmhmmhm Jul 12, 2026
ac40d6c
docs: record source size baseline
hmmhmmhm Jul 12, 2026
7f91af7
docs: plan app source decomposition
hmmhmmhm Jul 12, 2026
38794d1
test: define app source boundaries
hmmhmmhm Jul 12, 2026
dc69918
refactor(grok): reuse canonical spiral implementation
hmmhmmhm Jul 12, 2026
4042fe3
refactor(web): extract Earth grid helpers
hmmhmmhm Jul 13, 2026
69c2cb3
refactor(web): extract planetary map helpers
hmmhmmhm Jul 13, 2026
7716511
style(grok): format spiral re-export
hmmhmmhm Jul 13, 2026
0cb20a1
refactor(api): extract PostGIS selection helpers
hmmhmmhm Jul 13, 2026
14b11e8
docs: plan wordset decomposition
hmmhmmhm Jul 13, 2026
702b1af
test: define wordset source boundary
hmmhmmhm Jul 13, 2026
a7a991d
refactor(core): split wordset registry
hmmhmmhm Jul 13, 2026
618e929
docs: plan region runtime decomposition
hmmhmmhm Jul 13, 2026
27c1265
test(core): define region module boundaries
hmmhmmhm Jul 13, 2026
0e26b4b
refactor(core): decompose region runtime
hmmhmmhm Jul 13, 2026
a22a618
docs: plan spiral decomposition
hmmhmmhm Jul 13, 2026
6cebe87
test(core): define spiral source boundary
hmmhmmhm Jul 13, 2026
5f72c70
refactor(core): decompose spiral implementation
hmmhmmhm Jul 13, 2026
f7c8e97
docs: plan map container decomposition
hmmhmmhm Jul 13, 2026
43aefb2
test(web): define map hook source boundary
hmmhmmhm Jul 13, 2026
ddf277f
refactor(web): decompose map container hook
hmmhmmhm Jul 13, 2026
1f481b0
test(repo): define tooling source boundary
hmmhmmhm Jul 13, 2026
7e2fd8e
refactor(tooling): extract generator policy data
hmmhmmhm Jul 13, 2026
a0faf47
refactor(tooling): split language support data
hmmhmmhm Jul 13, 2026
3aecf56
refactor(tooling): split expanded language data
hmmhmmhm Jul 13, 2026
84af797
refactor(tooling): decompose address gap generator
hmmhmmhm Jul 13, 2026
13cd08a
refactor(tooling): decompose codebook policy audit
hmmhmmhm Jul 13, 2026
fd004d2
refactor(repo): split oversized test and ops modules
hmmhmmhm Jul 13, 2026
ccbcc02
fix(web): harden map and spiral browser loading
hmmhmmhm Jul 13, 2026
7cf28c2
fix(ci): repair split smoke validation
hmmhmmhm Jul 13, 2026
e534a59
docs: mark repository hardening plan complete
hmmhmmhm Jul 13, 2026
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 .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,12 @@ jobs:
- name: Install dependencies
run: pnpm install --frozen-lockfile

- name: Check formatting
run: pnpm format:check

- name: Check maintained source size
run: pnpm code:size-check

- name: Check API runtime pins
run: pnpm runtime:check-pins

Expand All @@ -45,6 +51,9 @@ jobs:
- name: Report URL label data
run: pnpm data:report-labels

- name: Lint
run: pnpm lint

- name: Type check
run: pnpm check-types

Expand All @@ -60,6 +69,9 @@ jobs:
- name: Test web client
run: pnpm --filter web test

- name: Build
run: pnpm build

- name: Install Playwright browser
run: pnpm --filter web exec playwright install --with-deps chromium

Expand Down
14 changes: 7 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,16 +32,16 @@ And Ground Codes is a **multi-planetary addressing system** 🪐 that provides a
- 🧠 **Simple and Memorable**: Just three words to identify any location precisely
- 🌎 **Global Coverage**: Works anywhere in the world with a unique address
- 🔓 **Open Source**: MIT licensed and fully transparent implementation
- 🌐 **Multilingual Support**: Currently available in English, Korean, Chinese, Japanese, Spanish, French, German, Portuguese, Indonesian, Thai, and Vietnamese, with plans to expand to 60 languages
- 🌐 **Multilingual Support**: 180 language sets include codebooks, localized UI copy, and Earth, Moon, and Mars region labels. All 180 pass the automated structural, regression, and minimum-score gates; native-speaker review remains ongoing maintenance.
- 🎯 **Variable Precision**: Offers three levels of precision (3m, 30cm, and 3cm) to suit different use cases

## 📊 Comparison with Similar Services

| Service | Format | License | Precision | Global Usage | Multilingual Support |
| ----------------------- | ----------------------- | --------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| 🌍 **Ground Codes** | Yongsan-Happiness-Smile | ✅ MIT License (Free) | 1. 3 meters (standard)<br>2. 30cm<br>3. 3cm | ✅ Yes | 🌐 English, Korean, Chinese, Japanese, Spanish, French, German, Portuguese, Indonesian, Thai, Vietnamese (expanding to 60 languages) |
| 🔍 **Google Plus Code** | HX2F+J8 | ⚠️ No License (Free) | 3.5 meters | ⚠️ Limited (requires 4 additional characters for global use, e.g., **8Q94HX2F+J8**) | 🇬🇧 English only |
| 🔤 **What 3 Words** | ///teacher.awaken.days | 💰 Proprietary (Paid) | 3 meters | ✅ Yes | 🌐 60 languages |
| Service | Format | License | Precision | Global Usage | Multilingual Support |
| ----------------------- | ----------------------- | --------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| 🌍 **Ground Codes** | Yongsan-Happiness-Smile | ✅ MIT License (Free) | 1. 3 meters (standard)<br>2. 30cm<br>3. 3cm | ✅ Yes | 🌐 180 automated-stable language sets; native-speaker review continues |
| 🔍 **Google Plus Code** | HX2F+J8 | ⚠️ No License (Free) | 3.5 meters | ⚠️ Limited (requires 4 additional characters for global use, e.g., **8Q94HX2F+J8**) | 🇬🇧 English only |
| 🔤 **What 3 Words** | ///teacher.awaken.days | 💰 Proprietary (Paid) | 3 meters | ✅ Yes | 🌐 60 languages |

## 💪 Advantages Over Existing Services

Expand Down Expand Up @@ -78,7 +78,7 @@ API usage is limited to 600 requests per minute per IP. For higher volume needs,
- 🇰🇷 Korean word set: 5,630 words (AI-generated dataset)
- 🇨🇳 Chinese word set: 5,140 words (AI-generated dataset)
- 🇯🇵 Japanese word set: 5,000 words (frequency-guided hiragana dataset)
- 🌐 Region labels: English, Korean, Chinese, Japanese, Spanish, French, German, Portuguese, Indonesian, Thai, and Vietnamese labels are available for Earth, Moon, and Mars datasets
- 🌐 Language coverage: 180 codebooks and localized UI/region-label sets are available for Earth, Moon, and Mars datasets
- 🌎 Region names: 210,000 unique global locations with populations of 500+ (GeoNames data, commercially usable)
- 🔐 Special solutions:
- **Region 1**: ✈️ Optimized for airports/logistics with country codes and airport codes (e.g., NYC-491AD, SSN-TA14C)
Expand Down
10 changes: 8 additions & 2 deletions apps/api-ground-codes/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ API Ground.codes is a RESTful API service built with Elysia.js and Bun that prov
- 🔄 **Encode Coordinates**: Convert latitude and longitude to memorable ground codes
- 🔍 **Decode Ground Codes**: Convert ground codes back to geographic coordinates
- 🌎 **Region Information**: Get information about specific regions
- 🌐 **Multilingual Support**: Support for multiple languages (English, Korean, Chinese, Japanese, Spanish, French, German, Portuguese, Indonesian, Thai)
- 🌐 **Multilingual Support**: 180 automated-stable codebook, UI, and Earth/Moon/Mars region-label sets; native-speaker review remains ongoing maintenance
- 🌕 **Planetary Bodies**: Encode Earth, Moon, and Mars coordinates with body-specific labels
- 🎯 **Customizable Precision**: Adjust the precision of encoded locations
- 📝 **Swagger Documentation**: Interactive API documentation
Expand Down Expand Up @@ -180,6 +180,12 @@ web app, and API route metrics. It records per-check response times for `/readyz
writes the timing table to the GitHub run summary. Add a `MOSHI_WEBHOOK_TOKEN`
repository secret to send a webhook alert when the smoke workflow fails.

`GET /metrics` exposes Worker-isolate metrics. The counters describe the
Cloudflare Worker isolate that handled the metrics request and are not a
globally aggregated request history. Production smoke validates the endpoint's
schema and numeric invariants without assuming earlier requests reached the same
isolate.

## 🔌 API Endpoints

### 🧩 Core Endpoints
Expand Down Expand Up @@ -315,7 +321,7 @@ Response:
The API supports various configuration options:

- 🏙️ **Region Level**: Choose between city names (level 2) or airport codes (level 1)
- 🌐 **Language**: Select from supported languages (English, Korean, Chinese, Japanese, Spanish, French, German, Portuguese, Indonesian, Thai)
- 🌐 **Language**: Select from 180 automated-stable language sets
- 📏 **Precision**: Adjust the precision of encoded locations in meters
- 🪐 **Body**: Select `earth`, `moon`, or `mars` for coordinate conversion and labels
- 🔐 **CORS**: Set `CORS_ALLOWED_ORIGINS` as a comma-separated production allowlist
Expand Down
224 changes: 224 additions & 0 deletions apps/api-ground-codes/src/app-part-2.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,224 @@
import { describe, expect, test } from "bun:test";
import { createApp } from "./app.js";

const app = createApp();
const rateLimitedApp = createApp({
rateLimit: {
max: 1,
windowMs: 60_000,
},
});

const postJson = (path: string, body: unknown) =>
app.handle(
new Request(`http://localhost${path}`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify(body),
}),
);

const get = (path: string) =>
app.handle(new Request(`http://localhost${path}`));

describe("Ground Codes API contract", () => {
test("encodes and searches Indonesian ground codes and region labels", async () => {
const encodedResponse = await postJson("/v1/encode", {
lat: -6.1751,
lng: 106.865,
language: "indonesian",
regionLevel: 2,
});
expect(encodedResponse.status).toBe(200);
const code = await encodedResponse.text();
expect(code).toMatch(/^Jakarta-[A-Z][A-Za-z]+/);

const codeSearchResponse = await postJson("/v1/search", {
query: code,
language: "english",
regionLevel: 2,
});
expect(codeSearchResponse.status).toBe(200);
const codeSearch = await codeSearchResponse.json();
expect(codeSearch.results[0]).toMatchObject({
type: "ground-code",
label: code,
body: "earth",
regionLevel: 2,
});

const regionSearchResponse = await postJson("/v1/search", {
query: "Jakarta",
language: "indonesian",
regionLevel: 2,
});
expect(regionSearchResponse.status).toBe(200);
const regionSearch = await regionSearchResponse.json();
expect(regionSearch.results[0]).toMatchObject({
type: "region",
label: "Jakarta",
body: "earth",
regionLevel: 2,
});
}, 90_000);

test("encodes and searches Thai ground codes and region labels", async () => {
const encodedResponse = await postJson("/v1/encode", {
lat: 13.7563,
lng: 100.5018,
language: "thai",
regionLevel: 2,
});
expect(encodedResponse.status).toBe(200);
const code = await encodedResponse.text();
expect(code).toMatch(/^กรุงเทพมหานคร-[\p{Script=Thai}]+/u);

const codeSearchResponse = await postJson("/v1/search", {
query: code,
language: "english",
regionLevel: 2,
});
expect(codeSearchResponse.status).toBe(200);
const codeSearch = await codeSearchResponse.json();
expect(codeSearch.results[0]).toMatchObject({
type: "ground-code",
label: code,
body: "earth",
regionLevel: 2,
});

const regionSearchResponse = await postJson("/v1/search", {
query: "กรุงเทพ",
language: "thai",
regionLevel: 2,
});
expect(regionSearchResponse.status).toBe(200);
const regionSearch = await regionSearchResponse.json();
expect(regionSearch.results[0]).toMatchObject({
type: "region",
label: "กรุงเทพมหานคร",
body: "earth",
regionLevel: 2,
});
}, 90_000);

test("encodes and searches Vietnamese ground codes and region labels", async () => {
const encodedResponse = await postJson("/v1/encode", {
lat: 21.0278,
lng: 105.8342,
language: "vietnamese",
regionLevel: 2,
});
expect(encodedResponse.status).toBe(200);
const code = await encodedResponse.text();
expect(code).toMatch(/^Hà Nội-[\p{Script=Latin}\p{Mark}]+/u);

const codeSearchResponse = await postJson("/v1/search", {
query: code,
language: "english",
regionLevel: 2,
});
expect(codeSearchResponse.status).toBe(200);
const codeSearch = await codeSearchResponse.json();
expect(codeSearch.results[0]).toMatchObject({
type: "ground-code",
label: code,
body: "earth",
regionLevel: 2,
});

const regionSearchResponse = await postJson("/v1/search", {
query: "Hà Nội",
language: "vietnamese",
regionLevel: 2,
});
expect(regionSearchResponse.status).toBe(200);
const regionSearch = await regionSearchResponse.json();
expect(regionSearch.results[0]).toMatchObject({
type: "region",
label: "Hà Nội",
body: "earth",
regionLevel: 2,
});
}, 90_000);

test("encodes and searches Hindi ground codes and region labels", async () => {
const encodedResponse = await postJson("/v1/encode", {
lat: 28.65195,
lng: 77.23149,
language: "hindi",
regionLevel: 2,
});
expect(encodedResponse.status).toBe(200);
const code = await encodedResponse.text();
expect(code).toMatch(/^दिल्ली-[\p{Script=Devanagari}\p{Mark}]+/u);

const codeSearchResponse = await postJson("/v1/search", {
query: code,
language: "english",
regionLevel: 2,
});
expect(codeSearchResponse.status).toBe(200);
const codeSearch = await codeSearchResponse.json();
expect(codeSearch.results[0]).toMatchObject({
type: "ground-code",
label: code,
body: "earth",
regionLevel: 2,
});

const regionSearchResponse = await postJson("/v1/search", {
query: "दिल्ली",
language: "hindi",
regionLevel: 2,
});
expect(regionSearchResponse.status).toBe(200);
const regionSearch = await regionSearchResponse.json();
expect(regionSearch.results[0]).toMatchObject({
type: "region",
label: "दिल्ली",
body: "earth",
regionLevel: 2,
});
}, 90_000);

test("encodes and searches Arabic ground codes and region labels", async () => {
const encodedResponse = await postJson("/v1/encode", {
lat: 30.0444,
lng: 31.2357,
language: "arabic",
regionLevel: 2,
});
expect(encodedResponse.status).toBe(200);
const code = await encodedResponse.text();
expect(code).toMatch(/^القاهرة-[\p{Script=Arabic}\p{Mark}]+/u);

const codeSearchResponse = await postJson("/v1/search", {
query: code,
language: "english",
regionLevel: 2,
});
expect(codeSearchResponse.status).toBe(200);
const codeSearch = await codeSearchResponse.json();
expect(codeSearch.results[0]).toMatchObject({
type: "ground-code",
label: code,
body: "earth",
regionLevel: 2,
});

const regionSearchResponse = await postJson("/v1/search", {
query: "القاهرة",
language: "arabic",
regionLevel: 2,
});
expect(regionSearchResponse.status).toBe(200);
const regionSearch = await regionSearchResponse.json();
expect(regionSearch.results[0]).toMatchObject({
type: "region",
label: "القاهرة",
body: "earth",
regionLevel: 2,
});
}, 90_000);
});
Loading