How iib0011/omni-tools works
1. Overall shape
- This is a client-side React + TypeScript single-page app built with Vite and deployed as static assets.
- The app’s core architectural boundary is simple: all tool processing runs in the browser; there is no application backend or user data upload path.
2. Primary product structure
- The repository is organized as a catalog of self-contained utilities across domains like image, video, PDF, CSV, JSON, string, time, list, number, audio, and XML.
- Each tool is usually isolated under src/pages/tools/<domain>/<tool-name>/, which makes the repo easy to diagram as many small feature modules under a shared app shell.
3. Tool module pattern
- Most tools follow the same internal split:
- index.tsx for the page/component entry
- service.ts for transformation logic
- meta.ts for tool metadata used by navigation, search, and localization
- types.ts or similar for tool-specific data contracts
- tests nearby (*.service.test.ts, some e2e specs)
- This gives a clear separation between UI, pure domain logic, and tool metadata.
4. Shared app shell
- Common layout and interaction components live in src/components/, such as:
- global shell/navigation (App, Navbar, Hero)
- tool framing (ToolLayout, ToolHeader, ToolContent, ToolInputAndResult, ToolBreadcrumb)
- reusable result/input panels and option controls
- These components provide the consistent “tool page” experience across the app, while individual tools plug into them.
5. Input/output pipeline
- The app is built around a standard user flow: select a tool → provide input → adjust options → compute result → export/download result.
- Input components cover text, code, numeric, image, audio, video, PDF, and multi-file cases.
- Output components mirror that shape with text results, file results, multi-file results, and diff/comparison views.
6. Routing and page grouping
- Tool pages are grouped by category under src/pages/tools/, with top-level pages for:
- home
- tools-by-category
- category index pages
- individual tool pages
- Route and UI configuration are centralized in src/config/routesConfig.tsx and related config files, so the app can render category landing pages and deep-link directly into each tool.
7. Domain logic and shared utilities
- Cross-cutting helper logic is concentrated in src/utils/, with utilities for arrays, files, CSV, JSON, numbers, strings, time, GIFs, color, and bookmarks.
- There are also domain data tables in src/datatables/ for calculator-style tools.
- This keeps the per-tool service.ts files focused and avoids duplicating parsing/formatting logic.
8. Browser-only heavy processing
- Some media/PDF tools depend on browser-side processing helpers in src/lib/ghostscript/, including worker bootstrapping files.
- This indicates that heavier transforms are offloaded to web workers rather than the main UI thread, which is important for diagramming performance boundaries.
9. Internationalization
- The app is fully localized through public/locales/<lang>/... JSON bundles.
- Translation management is supported by scripts that sync metadata with locale files, and the README notes Locize as the translation workflow.
- Architecturally, i18n is part of the tool metadata layer rather than a backend service.
10. State, context, and cross-cutting UI behavior
- Shared UI state is handled through React context/providers such as UserTypeFilterProvider and snackbar context.
- Hooks in src/hooks/ provide reusable behaviors like debounce, timeout, previous-value tracking, and update effects.
- These are support layers used across tool pages rather than business-specific subsystems.
11. Build, deployment, and runtime
- The app is packaged as a static web build; the Dockerfile and README show a lightweight container serving the built assets.
- public/_redirects suggests SPA fallback routing for static hosting.
- Testing is split between Vitest for unit/service tests and Playwright for end-to-end coverage, which reinforces that the primary runtime is the browser.
12. Tool generation and maintenance
- The repo includes scripts for generating new tools, maintaining i18n metadata, cleaning directories, and uploading translations.
- That implies the codebase is designed around a repeatable “new tool scaffold” workflow, with conventions enforced by folder structure rather than a backend or plugin registry.
13. What to draw as the main diagram boundary
- The most accurate architecture diagram would show:
- a static SPA shell
- a shared component/layout layer
- a tool registry/page tree
- tool-local service logic
- browser-native/Web Worker processing
- local i18n assets
- The key boundary is externalized services: essentially none in the runtime path; the app is intentionally self-contained on the client.
Main entry points: tools Tool tree · ToolLayout.tsx Tool shell · input Inputs · utils Utils
Components 34
App shell
Static SPA entry, routing, and shared page chrome.
Tool catalog
Category pages and representative tool modules.
- Home · Category-oriented landing page for browsing the tool catalog.
src/pages/home/index.tsx - By category · Category index view for navigating grouped tools.
src/pages/tools-by-category/index.tsx - Tool tree · Category entrypoints that organize the tool modules under src/pages/tools/.
src/pages/tools - String tools · Representative string utility pages backed by local service logic.
src/pages/tools/string - JSON tools · Representative JSON utility pages backed by local service logic.
src/pages/tools/json - CSV tools · Representative CSV utility pages backed by local service logic.
src/pages/tools/csv - Image tools · Representative image utilities, including browser-side media transforms.
src/pages/tools/image - PDF tools · Representative PDF utilities built for in-browser document processing.
src/pages/tools/pdf - Video tools · Representative video utilities for client-side transcoding and editing.
src/pages/tools/video - Audio tools · Representative audio utilities for client-side editing and conversion.
src/pages/tools/audio - Time tools · Representative time/date utilities and converters.
src/pages/tools/time - Tool defs · Shared tool-definition helper used to standardize tool metadata and module wiring.
src/tools/defineTool.tsx - Join text · Representative string tool composed from page UI and pure service logic.
src/pages/tools/string/join/index.tsx - Pretty JSON · Representative JSON formatting tool using browser-only parsing and display.
src/pages/tools/json/prettify/index.tsx - CSV to JSON · Representative CSV conversion tool focused on local transformation.
src/pages/tools/csv/csv-to-json/index.tsx - Resize image · Representative image editing tool that relies on client-side processing.
src/pages/tools/image/generic/resize/index.tsx - Merge PDF · Representative PDF operation that may offload work to browser workers.
src/pages/tools/pdf/merge-pdf/index.tsx - Trim video · Representative video editing tool for browser-side media manipulation.
src/pages/tools/video/trim/index.tsx - Trim audio · Representative audio editing tool for browser-side media manipulation.
src/pages/tools/audio/trim/index.tsx - Date span · Representative date/time utility for browser-side calculations.
src/pages/tools/time/time-between-dates/index.tsx
Shared infra
Reusable UI, state, hooks, utilities, and locale assets.
- Tool shell · Consistent tool-page framing, headers, breadcrumbs, and content layout.
src/components/ToolLayout.tsx - Inputs · Shared input controls for text, code, file, image, audio, video, PDF, and multi-file workflows.
src/components/input - Results · Shared output views for text, files, multi-file results, and diffs.
src/components/result - Options · Reusable option controls and grouped settings for tool configuration.
src/components/options - User filter · Shared React context for filtering the tool experience by user type.
src/providers/UserTypeFilterProvider.tsx - Snackbar · Global snackbar/notification context used across the app.
src/contexts/CustomSnackBarContext.tsx - Hooks · Reusable timing, debounce, and previous-value helpers.
src/hooks - Utils · Cross-cutting parsing, formatting, and transformation helpers shared by tool services.
src/utils - Locales · Localized translation bundles and app localization setup.
public/locales - Data tables · Calculator-style lookup tables used by numeric tools.
src/datatables
Heavy processing
Browser workers for expensive PDF/media transforms.
- Ghostscript · Web worker bootstrap and background processing for heavier PDF/media operations.
src/lib/ghostscript
Connections 48
- Entry → App: mounts · Bootstraps the React shell.
- App → Routes: uses routes · Renders pages according to centralized route configuration.
- Routes → Home: includes · Maps the home landing page.
- Routes → By category: includes · Maps category listing pages.
- Routes → Tool tree: maps · Deep-links into tool-category and tool pages.
- Home → Tool tree: browses · Entry point for navigating the catalog.
- By category → Tool tree: browses · Category browsing surfaces the tool tree.
- Tool tree → String tools: groups · String category contains multiple tool pages.
- Tool tree → JSON tools: groups · JSON category contains multiple tool pages.
- Tool tree → CSV tools: groups · CSV category contains multiple tool pages.
- Tool tree → Image tools: groups · Image category contains multiple tool pages.
- Tool tree → PDF tools: groups · PDF category contains multiple tool pages.
- Tool tree → Video tools: groups · Video category contains multiple tool pages.
- Tool tree → Audio tools: groups · Audio category contains multiple tool pages.
- Tool tree → Time tools: groups · Time category contains multiple tool pages.
- Tool tree → Tool defs: standardizes · Tool modules follow a shared definition pattern.
- String tools → Join text: contains · Representative tool module.
- JSON tools → Pretty JSON: contains · Representative tool module.
- CSV tools → CSV to JSON: contains · Representative tool module.
- Image tools → Resize image: contains · Representative tool module.
- PDF tools → Merge PDF: contains · Representative tool module.
- Video tools → Trim video: contains · Representative tool module.
- Audio tools → Trim audio: contains · Representative tool module.
- Time tools → Date span: contains · Representative tool module.
- Join text → Tool shell: renders with · Tool page uses the common shell and framing components.
- Pretty JSON → Tool shell: renders with · Tool page uses the common shell and framing components.
- CSV to JSON → Tool shell: renders with · Tool page uses the common shell and framing components.
- Resize image → Tool shell: renders with · Tool page uses the common shell and framing components.
- Merge PDF → Tool shell: renders with · Tool page uses the common shell and framing components.
- Trim video → Tool shell: renders with · Tool page uses the common shell and framing components.
- Trim audio → Tool shell: renders with · Tool page uses the common shell and framing components.
- Date span → Tool shell: renders with · Tool page uses the common shell and framing components.
- Join text → Utils: computes with · Service logic leans on shared helpers.
- Pretty JSON → Utils: computes with · Service logic leans on shared helpers.
- CSV to JSON → Utils: computes with · Service logic leans on shared helpers.
- Resize image → Utils: computes with · Service logic leans on shared helpers.
- Merge PDF → Ghostscript: offloads · Heavy document/media processing can run in worker-backed helpers.
- Trim video → Ghostscript: offloads · Heavy document/media processing can run in worker-backed helpers.
- Trim audio → Ghostscript: offloads · Heavy document/media processing can run in worker-backed helpers.
- Date span → Utils: computes with · Service logic leans on shared helpers.
- Resize image → Inputs: uses · Consumes shared input controls for local files and images.
- Merge PDF → Inputs: uses · Consumes shared input controls for local files and PDFs.
- Trim video → Inputs: uses · Consumes shared input controls for video files.
- Trim audio → Inputs: uses · Consumes shared input controls for audio files.
- Join text → Results: uses · Displays computed output through shared result views.
- Pretty JSON → Results: uses · Displays computed output through shared result views.
- CSV to JSON → Results: uses · Displays computed output through shared result views.
- Tool shell → Inputs: composes · Tool shell composes the input panel.