# joordih/zodiac-framework architecture

> Architecture diagram of the GitHub repository joordih/zodiac-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joordih/zodiac-framework
- Repository: https://github.com/joordih/zodiac-framework

## Overview

##### Project Type and Purpose
- The project is a modern, type-safe front-end framework specifically designed for creating Web Components. It is built using TypeScript and offers a variety of advanced features such as dependency injection, reactive state management with hooks, a forms system with validation, event management, routing (including typed routing), middleware integration, server-side rendering (SSR), and custom directives.
- In addition to the core framework code (found in the “src/core” directory), there’s also a “zodiac-compiler” section that appears to provide compilation support, likely to process or build projects using the framework. There’s also a “backend-test” directory for testing or demoing a server-side/node component (perhaps related to SSR or API integration).

##### Analyzing the File Structure
- The top-level directories include configuration files (package.json, tsconfig.json, etc.), “src” (containing the core library with dedicated subfolders for components, directives, events, forms, injection, middleware, rendering, routing, etc.), “backend-test” (a Node.js environment for testing or demonstrating backend-related functionality, possibly SSR or API endpoints), and “zodiac-compiler” (which houses the command-line compiler for the framework).
- Clearly, the architecture is modular – the “src/core” directory is broken down into specific concerns (e.g., “component”, “directives”, “injection”, “polyfills”, “ssr”, etc.), each forming a distinct building block of the framework.
- The presence of a “test” folder under “src/test” further reinforces that the framework includes sample implementations for components, services, and SSR-related scenarios.

##### Architectural Insights from the README
- The README highlights key features using TypeScript decorators, dependency injection, reactive state, form handling, typed events, routing, SSR, and directives. It also offers code snippets that illustrate how these features are implemented and used.
- There’s a clear separation of responsibilities: components manage rendering and lifecycle callbacks, while services, state managers, and middleware handle logic and data flow behind the scenes. The SSR section clearly indicates that the system supports both client-side hydration and server-side rendering.
- The examples show the intended usage patterns and how the various system parts interact (e.g., components using state management, forms using validators, middleware intercepting component lifecycle events, etc.).

##### Detailed & Essential Representation
– Avoid over-simplification: represent every module (such as “forms”, “router”, “directives”, “middleware”, “polyfills”) and show how they are interconnected.

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Framework Core"
    CS["Component System"]:::component
    CH["Hooks"]:::component
    CB["BaseComponent"]:::component
    DI["Dependency Injection"]:::service
    DIR["Directives"]:::service
    FORMS["Forms"]:::service
    VALID["Validation"]:::service
    STATE["State Management"]:::component
    EVENT["Event System"]:::component
    ROUTER["Router"]:::component
    SSR["SSR Engine"]:::service
    MID["Middleware"]:::service
    POLY["Polyfills"]:::util

    CS -->|"contains"| CH
    CS -->|"contains"| CB
  end

  subgraph "Compiler Module"
    COMP["Zodiac Compiler"]:::build
  end

  subgraph "Backend Testing/Integration"
    BACKEND["Backend Test Module"]:::backend
  end

  subgraph "Examples & Test Components"
    TESTCMP["Example Test Components"]:::example
  end

  CS -->|"uses"| DI
  CS -->|"integrates"| STATE
  CS -->|"dispatches"| EVENT
  CS -->|"applies"| DIR
  CS -->|"handles"| FORMS
  CS -->|"validates"| VALID
  CS -->|"routes"| ROUTER
  CS -->|"renders_via"| SSR
  CS -->|"intercepts"| MID

  DI -->|"injects_into"| CS
  STATE -->|"updates"| CS
  EVENT -->|"triggers"| CS
  FORMS -->|"submits_to"| MID

  SSR -->|"hydrates"| ROUTER

  COMP -->|"compiles"| CS

  BACKEND -->|"tests"| SSR

  TESTCMP -->|"demonstrates"| CS

  click CS "https://github.com/joordih/zodiac-framework/tree/main/src/core/component"
  click CH "https://github.com/joordih/zodiac-framework/tree/main/src/core/component/hooks"
  click CB "https://github.com/joordih/zodiac-framework/blob/main/src/core/component/baseComponent.ts"
  click DI "https://github.com/joordih/zodiac-framework/tree/main/src/core/injection"
  click DIR "https://github.com/joordih/zodiac-framework/tree/main/src/core/directives"
  click FORMS "https://github.com/joordih/zodiac-framework/tree/main/src/core/forms"
  click VALID "https://github.com/joordih/zodiac-framework/tree/main/src/core/validation"
  click STATE "https://github.com/joordih/zodiac-framework/tree/main/src/core/state"
  click EVENT "https://github.com/joordih/zodiac-framework/tree/main/src/core/events"
  click ROUTER "https://github.com/joordih/zodiac-framework/tree/main/src/core/router"
  click SSR "https://github.com/joordih/zodiac-framework/tree/main/src/core/ssr"
  click MID "https://github.com/joordih/zodiac-framework/tree/main/src/core/middleware"
  click POLY "https://github.com/joordih/zodiac-framework/tree/main/src/core/polyfills"
  click COMP "https://github.com/joordih/zodiac-framework/tree/main/zodiac-compiler"
  click BACKEND "https://github.com/joordih/zodiac-framework/tree/main/backend-test"
  click TESTCMP "https://github.com/joordih/zodiac-framework/tree/main/src/test"

  classDef component fill:#f9f,stroke:#333,stroke-width:2px;
  classDef service fill:#bbf,stroke:#333,stroke-width:2px;
  classDef build fill:#afa,stroke:#333,stroke-width:2px;
  classDef backend fill:#ffa,stroke:#333,stroke-width:2px;
  classDef example fill:#cff,stroke:#333,stroke-width:2px;
  classDef util fill:#ddd,stroke:#333,stroke-width:2px;
```
