sokuji - Moses Yebei

The Problem

Users need real‑time speech translation on desktop or in‑browser without juggling separate capture, AI, and UI components. Existing tools are either closed‑source, platform‑restricted, or require manual wiring of audio pipelines and API keys.

What This Does

sokuji ships six self‑contained projects that together deliver live translation via OpenAI, Google Gemini, Palabra.ai, and Kizuna AI.

The Electron app (electron/main.js) boots a Chromium window that loads src/index.html, which mounts the React tree under src/components/MainPanel/MainPanel.tsx.
The browser extension lives in extension/, built with Webpack (extension/webpack.config.js) and packaged for Chrome/Edge.
Eval scripts (evals/runner/cli.ts, evals/runner/index.ts) provide a CLI harness for automated testing of audio‑service integrations.
Shared utilities (src/lib/analytics.ts, src/utils/environment.ts) and type definitions (src/types/Provider.ts) are reused across all projects.

How It Is Wired

Execution starts in electron/main.js (or docs/index.html for the web demo). The main process creates a BrowserWindow, then the renderer loads src/index.html, which runs the bundled React entry (src/main.tsx). React renders MainPanel – the UI hub that orchestrates audio capture, AI client selection, and result display.

Audio flow – src/lib/modern-audio/ModernBrowserAudioService is instantiated by src/services/ServiceFactory.ts (via createAudioService). The service emits raw PCM to the selected AI client (src/services/clients/*Client.ts).
AI clients implement src/services/interfaces/IClient. The concrete classes (GeminiClient, OpenAIClient, etc.) are selected based on src/types/Provider.ts and user settings stored in src/stores/settingsStore.ts.
Analytics – src/lib/analytics.ts subscribes to events from settingsStore, audioStore, and UI components, sending data to PostHog. This module is a hub (22 inbound imports) and participates in a circular import with audioStore and ServiceFactory.
State management – Redux‑style stores (src/stores/*Store.ts) expose observable state; MainPanel reads settingsStore and audioStore to drive UI updates.
Extension – extension/background.ts mirrors the same service factory logic but runs in a service worker, communicating with content scripts via Chrome messaging.

Circular dependencies (35 edges) involve analytics.ts, audioStore.ts, and ServiceFactory.ts; they increase change‑impact risk because a modification can trigger recompilation of multiple bundles. The most fan‑in module (src/types/Provider.ts) is a stability anchor – keep its API minimal.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/sokuji.git
cd sokuji

# Install all npm workspaces
npm ci

# Copy example env and fill in your API keys
cp .env.example .env
# edit .env → set OPENAI_API_KEY, GEMINI_API_KEY, etc.

# Run the desktop app (development mode)
npm run dev   # defined in package.json, invokes electron/main.js via vite

# Build the browser extension
npm run build:extension   # uses extension/webpack.config.js, outputs to dist/

The Electron app reads .env at startup; the extension expects the same variables injected at build time (see docs/README.md for details). No additional database or server is required.

Real‑World Use

A remote‑learning platform can embed the extension in its web UI. When a teacher speaks, ModernBrowserAudioService captures the microphone stream, forwards it to OpenAIClient via the Realtime API, and the translated subtitles are injected into the video element by the content script (extension/contentScript.ts). The same flow works in the desktop app for standalone meetings.

Code Health & Issues

High – Pin third‑party GitHub Actions to commit SHAs (.github/workflows/*).
Medium – Add Dependabot (.github/dependabot.yml).
Medium – Gate PRs with a dependency‑vulnerability scan (dependency-review-action or osv-scanner).
Medium – Move large binary screenshots/demo.mp4 (5.8 MiB) to Git LFS.
Medium – Set persist-credentials: false on checkout steps (.github/workflows/build.yml).
Medium – Expand test coverage; only 1 test file covers 131 source files (ratio 0.008).
Low – Define timeout-minutes on CI jobs.
Low – Add convention files (.editorconfig, .gitattributes, formatter config).

Static analysis also flagged 40 import‑cycle members, six oversized files (e.g., src/components/MainPanel/MainPanel.tsx at 740 lines), and deep nesting (max depth 8) in UI components. These patterns inflate cognitive load and increase the blast radius of changes.

The Bottom Line

sokuji provides a functional, cross‑platform live translation stack with clear entry points and reusable service factories, but the codebase suffers from import cycles, large monolithic modules, and modest test coverage. It is suitable for teams that need a quick prototype or are willing to invest in refactoring the identified hotspots.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

398 files

JSON102
TypeScript67
Markdown42
TSX39
HTML26
JavaScript25

React

Module dependencies

The 10 most depended-upon modules of 131, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_types_Provider["Provider"] n1_src_lib_analytics["analytics"] n2_src_utils_environment["environment"] n3_src_stores_settingsStore["settingsStore"] n4__services_interfaces_IClient["IClient"] n5_evals_runner_types["types"] n6_src_stores_audioStore["audioStore"] n7_src_lib_auth_hooks["hooks"] n8_ces_providers_ProviderConfig["ProviderConfig"] n9_onents_Settings_shared_hooks["hooks"] n4__services_interfaces_IClient --> n0_src_types_Provider n3_src_stores_settingsStore --> n8_ces_providers_ProviderConfig n3_src_stores_settingsStore --> n4__services_interfaces_IClient n3_src_stores_settingsStore --> n0_src_types_Provider n0_src_types_Provider --> n2_src_utils_environment classDef cyc stroke:#ef4444,stroke-width:2px; class n1_src_lib_analytics,n6_src_stores_audioStore cyc;

Dependencies

40 of 72 declared dependencies are a major version behind. Resolved 72 of 72 against the registry.

Package	Declared	Latest	Behind
`electron`	^34.0.0	43.4.0	9 major
`@types/node`	^20.12.7	26.2.0	6 major
`jsdom`	^24.0.0	30.0.1	6 major
`sass-loader`	^13.3.2	17.0.0	4 major
`web-vitals`	^2.1.4	6.1.1	4 major
`copy-webpack-plugin`	^11.0.0	14.0.0	3 major
`@testing-library/react`	^13.4.0	16.3.2	3 major
`@types/jest`	^27.5.2	30.0.0	3 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium5

low2

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

softprops/action-gh-release@v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium

screenshots/demo.mp4

1 blobs over 5MB: demo.mp4 5.8MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/build.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Expand the test suite; it cannot cover this codebasemedium

1 test files against 131 source files (ratio 0.008)

A reviewer reads "has tests" and assumes a safety net that covers two files out of eighty-five, which is how untested paths ship behind a green badge.

Fix: Add tests for the highest fan-in modules first.

Set timeout-minutes on the workflow jobslow

.github/workflows/build.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.