From 18ba2b4cb39275934f38f34b883da807aa8d20a5 Mon Sep 17 00:00:00 2001
From: Mingjing <1239443+hackergene@users.noreply.github.com>
Date: Tue, 11 Aug 2026 16:29:54 +0800
Subject: [PATCH] docs: clarify SwiftUI and JavaScript architecture

---
 README.md       | 18 ++++++++++++++++++
 README.zh-CN.md | 18 ++++++++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/README.md b/README.md
index 19dfcb0..b3e2bf1 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,8 @@ Codex workspace a visual identity while keeping the official app intact and
 making every change reversible.
 
 [![macOS 13+](https://img.shields.io/badge/macOS-13%2B-111827?logo=apple)](https://github.com/hackergene/AI-ThemeStore-Community/releases/latest)
+[![SwiftUI App](https://img.shields.io/badge/app-SwiftUI-F05138?logo=swift&logoColor=white)](#technology-stack)
+[![JavaScript Engine](https://img.shields.io/badge/engine-JavaScript-F7DF1E?logo=javascript&logoColor=111827)](#technology-stack)
 [![MIT License](https://img.shields.io/badge/license-MIT-25D9FF.svg)](./LICENSE)
 [![Offline](https://img.shields.io/badge/runtime-offline-8A6CFF.svg)](#privacy-and-safety)
 
@@ -37,6 +39,22 @@ No third-party character fan art is included in this repository.
 - Signature checks for the official Codex app and its bundled Node.js runtime
 - No accounts, analytics, cloud registry, remote devices, or automatic updates
 
+## Technology stack
+
+AI ThemeStore Community is a hybrid native macOS app: **Swift and SwiftUI**
+provide the application interface, while a local **JavaScript and CSS theme
+engine** handles Codex theming, verification, and recovery.
+
+| Layer | Technology | Responsibility |
+| --- | --- | --- |
+| Native app | Swift, SwiftUI | Theme library, controls, status, and user-facing recovery |
+| Theme engine | JavaScript (ESM), CSS | Apply themes and verify New Chat and active task surfaces |
+| Lifecycle tools | POSIX shell | Start, pause, restore, diagnose, and build the app |
+| Build system | Swift Package Manager | Compile and package the native macOS application |
+
+GitHub's language label is based on source-code byte count, so it may show
+JavaScript even though the user-facing application is native SwiftUI.
+
 ## What we learned from theming Codex
 
 Codex is a living product, so a durable theme cannot be just a wallpaper or a
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 05f928d..ccba5ea 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -8,6 +8,8 @@
 工作区加入完整的视觉主题，同时保持官方 App 完整，所有改动均可恢复。
 
 [![macOS 13+](https://img.shields.io/badge/macOS-13%2B-111827?logo=apple)](https://github.com/hackergene/AI-ThemeStore-Community/releases/latest)
+[![SwiftUI App](https://img.shields.io/badge/app-SwiftUI-F05138?logo=swift&logoColor=white)](#技术栈)
+[![JavaScript Engine](https://img.shields.io/badge/engine-JavaScript-F7DF1E?logo=javascript&logoColor=111827)](#技术栈)
 [![MIT License](https://img.shields.io/badge/license-MIT-25D9FF.svg)](./LICENSE)
 [![Offline](https://img.shields.io/badge/runtime-offline-8A6CFF.svg)](#隐私与安全)
 
@@ -33,6 +35,22 @@
 - 校验官方 Codex App 及其内置 Node.js 运行时的签名
 - 不包含账号、遥测、云端 Registry、远程设备或自动更新
 
+## 技术栈
+
+AI ThemeStore Community 是一套混合架构的原生 macOS App：**Swift 与
+SwiftUI** 提供应用界面，本地 **JavaScript 与 CSS 主题引擎**负责 Codex
+主题应用、验证和恢复。
+
+| 层级 | 技术 | 职责 |
+| --- | --- | --- |
+| 原生 App | Swift、SwiftUI | 主题库、控制界面、状态展示和用户侧恢复 |
+| 主题引擎 | JavaScript（ESM）、CSS | 应用主题并验证 New Chat 与运行中任务界面 |
+| 生命周期工具 | POSIX shell | 启动、暂停、恢复、诊断和构建 App |
+| 构建系统 | Swift Package Manager | 编译和打包原生 macOS 应用 |
+
+GitHub 的语言标签依据源码字节数计算，因此即使用户看到的是原生 SwiftUI App，
+仓库仍可能显示 JavaScript。
+
 ## 适配 Codex 的实践经验
 
 Codex 是持续演进的产品，因此稳定主题不能只是一张壁纸，也不能依赖一组脆弱的