Kimesh System Architecture
Version: 0.2.23 Status: Active Development Last Updated: January 28, 2026
Architecture Overview
Kimesh is a layered architecture framework combining build-time code generation with runtime Vue 3 integration. The system is organized into three primary phases:
- Build-Time Phase: Static code generation and type generation
- Runtime Phase: Vue Router integration and middleware execution
- Development Phase: Hot Module Replacement and incremental updates
High-Level Architecture Diagram
┌─────────────────────────────────────────────────────────────┐
│ Kimesh Application │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ File System │ │ Config Files │ │ Modules │ │
│ │ (src/routes) │ │ (kimesh.conf)│ │ (layers/) │ │
│ └──────────┬───┘ └──────────┬───┘ └──────────┬───┘ │
│ │ │ │ │
│ └─────────────────┴─────────────────┘ │
│ │ │
│ BUILD-TIME PHASE (Vite) │
│ │ │
│ ┌──────────────────▼───────────────────┐ │
│ │ @kimesh/kit Vite Plugin │ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │ Phase 1: Discovery & Merging │ │ │
│ │ │ • Route scanning (src/routes) │ │ │
│ │ │ • Layer resolution │ │ │
│ │ │ • Config loading & validation │ │ │
│ │ └─────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────┐ │ │
│ │ │ Phase 2: Code Generation │ │ │
│ │ │ • Route generation │ │ │
│ │ │ • Type generation │ │ │
│ │ │ • Component registration │ │ │
│ │ │ • Auto-import registry │ │ │
│ │ └─────────────────────────────────┘ │ │
│ └──────────────┬───────────────────────┘ │
│ │ │
│ ┌─────────┴──────────┬─────────────┐ │
│ │ │ │ │
│ Generated Files: │ │
│ • .kimesh/routes.gen.ts │ │
│ • .kimesh/typed-routes.d.ts │ │
│ • .kimesh/imports.gen.ts │ │
│ • .kimesh/components.gen.ts │ │
│ │ │
│ RUNTIME PHASE │ │
│ │ │
│ ┌───────────────────────────────────────▼───┐ │
│ │ Vue 3 Application │ │
│ │ ┌────────────────────────────────────┐ │ │
│ │ │ Router Initialization │ │ │
│ │ │ (@kimesh/router-runtime) │ │ │
│ │ │ • Route matching │ │ │
│ │ │ • Middleware pipeline │ │ │
│ │ │ • Navigation guards │ │ │
│ │ └────────────────────────────────────┘ │ │
│ │ ┌────────────────────────────────────┐ │ │
│ │ │ Component Rendering │ │ │
│ │ │ • Page components │ │ │
│ │ │ • Layouts │ │ │
│ │ │ • Auto-imported components │ │ │
│ │ └────────────────────────────────────┘ │ │
│ │ ┌────────────────────────────────────┐ │ │
│ │ │ Data Management │ │ │
│ │ │ (@kimesh/query) │ │ │
│ │ │ • Query execution │ │ │
│ │ │ • Cache management │ │ │
│ │ │ • Mutations │ │ │
│ │ └────────────────────────────────────┘ │ │
│ │ ┌────────────────────────────────────┐ │ │
│ │ │ Meta/Head Management │ │ │
│ │ │ (@kimesh/head) │ │ │
│ │ │ • Title updates │ │ │
│ │ │ • Meta tags │ │ │
│ │ │ • SEO optimization │ │ │
│ │ └────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘Build-Time Architecture
Phase 1: Discovery & Configuration
Input: File system and configuration files Output: Unified configuration and discovered artifacts
┌──────────────────────────────────────────────────┐
│ Phase 1: Discovery & Configuration │
│ │
│ 1. Configuration Loading │
│ • Read kimesh.config.ts │
│ • Load layer configurations │
│ • Merge configs (defu) │
│ • Validate configuration │
│ │
│ 2. Route Discovery │
│ • Scan src/routes directory │
│ • Parse file names for patterns │
│ • Detect layouts and nesting │
│ • Build route tree │
│ │
│ 3. Layer Resolution │
│ • Discover layer directories │
│ • Resolve layer inheritance │
│ • Collect layer components │
│ • Merge layer configs │
│ │
│ 4. Component & Import Discovery │
│ • Scan src/components │
│ • Build component registry │
│ • Detect imports needed │
│ • Resolve alias paths │
└──────────────────────────────────────────────────┘Key Packages:
@kimesh/layers- Layer discovery and merging@kimesh/router-generator- Route scanning and merging@kimesh/auto-import- Import registry building@kimesh/kit- Configuration loading and validation
Phase 2: Code Generation
Input: Configuration and discovered artifacts Output: Generated files in .kimesh/
┌──────────────────────────────────────────────────┐
│ Phase 2: Code Generation │
│ │
│ 1. Route Generation │
│ • Generate route definitions │
│ • Create route tree structure │
│ • Generate type definitions │
│ • Optimize for tree-shaking │
│ Output: .kimesh/routes.gen.ts │
│ .kimesh/typed-routes.d.ts │
│ │
│ 2. Type Generation │
│ • Generate TypeScript definitions │
│ • Create type-safe route helpers │
│ • Generate component types │
│ • Add IDE autocomplete support │
│ Output: .kimesh/*.d.ts files │
│ │
│ 3. Import Registry Generation │
│ • Build auto-import registry │
│ • Generate import injector code │
│ • Handle name conflicts │
│ • Create registry template │
│ Output: .kimesh/imports.gen.ts │
│ │
│ 4. Component Registry │
│ • Generate component registry │
│ • Auto-register global components │
│ • Create component type map │
│ • Support async components │
│ Output: .kimesh/components.gen.ts │
│ │
│ 5. Alias Resolution │
│ • Generate tsconfig path aliases │
│ • Create layer aliases │
│ • Resolve module paths │
│ • Update module map │
│ Output: .kimesh/tsconfig.json │
└──────────────────────────────────────────────────┘Key Packages:
@kimesh/kit- Main code generation orchestrator@kimesh/router-generator- Route file generation@kimesh/auto-import- Import registry templates@kimesh/layers- Alias and layer generation
Runtime Architecture
Router Integration
Vue 3 App Initialization
│
▼
┌──────────────────────────┐
│ createKimeshApp() │
│ • Initialize router │
│ • Setup middleware │
│ • Configure plugins │
└────────┬─────────────────┘
│
▼
┌──────────────────────────┐
│ Router Setup │
│ • Load routes.gen.ts │
│ • Setup navigation │
│ • Register guards │
└────────┬─────────────────┘
│
▼
┌──────────────────────────┐
│ Navigation Pipeline │
│ 1. Route matching │
│ 2. Before guards │
│ 3. Layout resolution │
│ 4. Component loading │
│ 5. Data loading │
│ 6. After guards │
│ 7. Render │
└──────────────────────────┘Middleware Pipeline
The middleware pipeline provides extensibility for request/response handling:
typescript
// Request -> Middleware Chain -> Response
Navigation Request
│
▼
┌─────────────────────────┐
│ beforeResolve Guards │
│ (can prevent nav) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Layout Resolution │
│ (find parent layouts) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Component Loading │
│ (lazy load if needed) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Data Loader Execution │
│ (route.loader()) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ afterResolve Guards │
│ (post-resolution) │
└────────┬────────────────┘
│
▼
Component RenderKey Packages:
@kimesh/router-runtime- Router initialization@kimesh/router-runtime- Middleware pipeline- Vue Router 3.5+ - Underlying router
Component & Auto-Import System
Source Code
│
▼
┌───────────────────────────┐
│ OXC Scanner │
│ Parse JavaScript/TypeScript
│ • Detect component usage │
│ • Find references │
│ • Build import map │
└────────┬──────────────────┘
│
▼
┌───────────────────────────┐
│ Import Registry │
│ • Resolve component names │
│ • Handle conflicts │
│ • Match against sources │
└────────┬──────────────────┘
│
▼
┌───────────────────────────┐
│ Import Injection │
│ • Add import statements │
│ • Register components │
│ • Update source files │
└───────────────────────────┘Key Packages:
@kimesh/auto-import- OXC scanning and injection@kimesh/auto-import- Component resolver- OXC Library - AST parsing
Plugin System Architecture
Three Types of Plugins
1. Kit Plugins (Build-Time)
Plugins that run during the build process:
typescript
interface KitPlugin {
name: string
apply?: 'pre' | 'post' | 'normal'
// Hooks available
'kit:config'?(config: KimeshConfig): void
'kit:discovered'?(discovered: DiscoveredArtifacts): void
'kit:generated'?(generated: GeneratedFiles): void
}Usage: Extend build process, modify routes, add custom generation
2. Vite Plugins
Standard Vite plugins integrated into the build:
typescript
interface VitePlugin {
name: string
apply?: 'serve' | 'build'
resolveId?(id: string): string | null
load?(id: string): string | null
transform?(code: string, id: string): void
}Usage: Custom module resolution, code transformation, HMR
3. Runtime Plugins
Plugins that run in the browser:
typescript
interface RuntimePlugin {
name: string
install(app: App): void
}Usage: Extend Vue app, add composables, register components
Plugin Loading Order
1. Load kimesh.config.ts
2. Discover layer plugins
3. Initialize Kit Plugins (build-time)
4. Run Phase 1 (Discovery)
5. Run Phase 2 (Code Generation)
6. Load Vite Plugins
7. Initialize Runtime Plugins (browser)
8. App initializationLayer System Architecture
Layers enable modular, reusable configurations:
┌─────────────────────────────────────┐
│ Kimesh App │
├─────────────────────────────────────┤
│ │
│ Layer Stack: │
│ ┌──────────────────────────────┐ │
│ │ Feature Layer (specific) │ │ Top (wins on conflicts)
│ │ - Custom routes │ │
│ │ - Feature modules │ │
│ │ - Feature components │ │
│ └──────────────────────────────┘ │
│ ┌──────────────────────────────┐ │
│ │ Base Layer (shared) │ │ Middle (provides defaults)
│ │ - Core routes │ │
│ │ - Shared components │ │
│ │ - Base layout │ │
│ └──────────────────────────────┘ │
│ ┌──────────────────────────────┐ │
│ │ Framework Defaults │ │ Bottom (baseline)
│ │ - Router config │ │
│ │ - Default modules │ │
│ │ - Type definitions │ │
│ └──────────────────────────────┘ │
│ │
│ Resolution: Top → Bottom │
│ First match wins │
└─────────────────────────────────────┘Key Packages:
@kimesh/layers- Layer discovery and merging
Route Merging System
The route merger combines app routes with layer routes based on file structure matching:
┌─────────────────────────────────────────────────────────────┐
│ Route Merging - Matching Scenarios │
├─────────────────────────────────────────────────────────────┤
│ │
│ CASE 1: Layout Route Matching (by routePath) │
│ ───────────────────────────────────────────── │
│ App: blog.vue (layout) Layer: blog/index.vue │
│ → Layer nested under app's blog layout │
│ │
│ CASE 2: Pathless Layout Matching (by filePath structure) │
│ ───────────────────────────────────────────── │
│ App: _dashboard/ Layer: _dashboard/reports.vue │
│ home.vue │
│ → Layer's _dashboard/* routes merge under app's _dashboard │
│ (Layer filePath must start with rawSegment: '_dashboard/') │
│ │
│ CASE 3: Sibling Addition (no match) │
│ ───────────────────────────────────────────── │
│ App: _dashboard/ Layer: blog/index.vue │
│ home.vue │
│ → Layer added as sibling under __root │
│ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Merge Algorithm │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. collectRoutesRecursively(appChildren) │
│ • Builds map: routePath → { route, pathlessParent } │
│ • Recursively enters pathless layouts (routePath='') │
│ • Skips dynamic routes (contains ':') │
│ │
│ 2. For each layerRoute: │
│ a. Check if app has matching layout by routePath │
│ → Yes: Nest layer under that layout │
│ b. Check if layer's filePath matches pathless rawSegment │
│ → Yes: Add under that pathless layout │
│ c. No match: Add as sibling under root layout │
│ │
│ 3. Sort children: pathless without index first │
│ │
└─────────────────────────────────────────────────────────────┘Key Rules:
- Layout matching: Layer
blog/x.vuematches appblog.vuelayout by routePath - Pathless matching: Layer
_dashboard/x.vuematches app_dashboard/by filePath prefix - rawSegment property: Stores original folder name (e.g.,
_dashboard) for matching - Recursive collection: Nested pathless layouts (
_a/_b/) are flattened into map
Context-Aware Layer Alias Plugin
The layerAliasPlugin resolves ~/ and @/ aliases based on the importing file's layer:
┌─────────────────────────────────────────────────────────────┐
│ Context-Aware Alias Resolution │
├─────────────────────────────────────────────────────────────┤
│ │
│ Import in layer/src/routes/feature.vue: │
│ import Sidebar from '@/components/Sidebar.vue' │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ 1. Find Layer for Importer │ │
│ │ findLayerForFile(importer) │ │
│ │ • Resolve symlinks │ │
│ │ • Match longest layer path │ │
│ └─────────────────┬───────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ 2. Resolve Alias Relative to Layer │ │
│ │ @/ → layer/src/ │ │
│ │ ~/ → layer/ │ │
│ └─────────────────┬───────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ 3. Try Extensions & Index Files │ │
│ │ .ts, .js, .vue, index.ts, etc. │ │
│ └─────────────────────────────────────┘ │
│ │
│ Result: layer/src/components/Sidebar.vue ✅ │
│ (not host/src/components/Sidebar.vue) │
│ │
└─────────────────────────────────────────────────────────────┘Handles:
- Regular imports via
resolveId - Virtual modules (kimesh-route:) via
transform - Symlinked layer paths
Hot Module Replacement (HMR)
HMR enables fast development iteration:
File Change Detected
│
▼
┌─────────────────────┐
│ File Watcher │
│ (Vite integration) │
└────────┬────────────┘
│
▼
┌─────────────────────┐
│ Identify Change │
│ • Route file? │
│ • Config file? │
│ • Component? │
└────────┬────────────┘
│
▼
┌─────────────────────┐
│ Regenerate Code │
│ • Update routes.gen │
│ • Update types │
│ • Update imports │
└────────┬────────────┘
│
▼
┌─────────────────────┐
│ HMR Update │
│ • Send to browser │
│ • Hot reload │
│ • Preserve state │
└─────────────────────┘Target: < 500ms HMR update time
Key Packages:
@kimesh/kit- HMR watcher and update logic
Data Management Architecture
Query System (TanStack Query Integration)
Component
│
▼
┌──────────────────────┐
│ useQuery() │
│ @kimesh/query │
└────────┬─────────────┘
│
▼
┌──────────────────────┐
│ Query Client │
│ • Cache management │
│ • Request dedup │
│ • Stale handling │
└────────┬─────────────┘
│
▼
┌──────────────────────┐
│ Fetch Function │
│ • API call │
│ • Error handling │
│ • Retry logic │
└────────┬─────────────┘
│
▼
┌──────────────────────┐
│ Cache & State │
│ • Store result │
│ • Update component │
│ • Background refetch │
└──────────────────────┘Features:
- Automatic request deduplication
- Background fetching and refetching
- Request cancellation
- Optimistic updates
- Infinite queries
- Paginated queries
Key Packages:
@kimesh/query- Query wrapper and utilities
State Management (Pinia Module)
Pinia Store
│
├─ State (reactive data)
├─ Getters (computed)
├─ Actions (mutations)
│
└─ DevTools Integration
(time-travel debugging)Key Packages:
@kimesh/pinia- Pinia module integration
Head/Meta Management Architecture
Route Configuration
│
▼
┌────────────────────────┐
│ Head Components │
│ <KmHead>, <KmTitle> │
│ <KmMeta>, <KmLink> │
└────────┬───────────────┘
│
▼
┌────────────────────────┐
│ @unhead/vue │
│ • Title management │
│ • Meta tag generation │
│ • SEO optimization │
└────────┬───────────────┘
│
▼
Document Head <head>
• <title>
• <meta>
• <link>
• <script>
• <style>Key Packages:
@kimesh/head- Head components and composables@unhead/vue- Underlying head management
CLI Architecture
Command Pipeline
CLI Input
│
▼
┌──────────────┐
│ Parse Args │
└────────┬─────┘
│
▼
┌──────────────┐
│ Load Config │
└────────┬─────┘
│
▼
┌──────────────┐
│ Execute Cmd │
│ • init │
│ • dev │
│ • build │
│ • generate │
│ • prepare │
│ • layer │
└────────┬─────┘
│
▼
OutputKey Packages:
@kimesh/cli- Command implementations@kimesh/kit- Build orchestration
Type Generation Strategy
Multi-Level Type Generation
Level 1: Route Types
• Path parameters (<id>, <slug>)
• Query parameters (?q=)
• Meta properties
Level 2: Component Types
• Props inference
• Event inference
• Slot types
Level 3: Query Types
• Request shape
• Response shape
• Error types
Level 4: Auto-Import Types
• Component auto-completion
• Function auto-completion
• Type-safe importsOutput: .kimesh/*.d.ts files for IDE support
Security Architecture
Input Validation
User Input
│
▼
┌────────────────────────┐
│ Validate Configuration │
│ • Check types │
│ • Validate paths │
│ • Sanitize strings │
└────────┬───────────────┘
│
├─ Valid? ──> Continue
│
└─ Invalid? ──> Throw ErrorTemplate Safety
Code Generation
│
▼
┌────────────────────────┐
│ Sanitize Templates │
│ • Escape output │
│ • Avoid injection │
│ • Use type-safe gen │
└────────┬───────────────┘
│
▼
Generated Code (safe)Performance Optimization
Build Performance
- Incremental Generation: Only regenerate changed files
- OXC Parsing: 100x faster than JavaScript-based parsing
- Parallel Builds: Turborepo task parallelization
- Caching: Layer resolution caching
- Lazy Bundling: Code split for better tree-shaking
Runtime Performance
- Lazy Route Loading: Code split route components
- Prefetching: Preload likely next routes
- Cached Queries: TanStack Query caching
- Component Lazy Loading: Async component support
- Tree-Shaking: Named exports for optimal bundle
Extensibility Points
User Application
│
├─ Kit Plugins (build-time customization)
├─ Runtime Plugins (app customization)
├─ Custom Modules (feature additions)
├─ Layers (configuration inheritance)
└─ Middleware (request handling)References
- Build System:
@kimesh/kit - Router:
@kimesh/router-runtime - Code Generation:
@kimesh/router-generator,@kimesh/auto-import - Configuration:
@kimesh/layers,@kimesh/kit - CLI:
@kimesh/cli