How KB4IT is built

KB4IT in kb4it/core/main.py reads the command line, takes the process lock, sets up logging and registers the services. Each service asks the controller for the others by name. The Processor, Compiler and Deployer are different: they belong to one build, so the Backend makes them together, as backend.pipeline (services/pipeline.py), once the theme is loaded, and gives each the services it needs.

The terminal interface (kb4it/tui/) is a Textual application: app.py starts it, screens/ holds one module per screen. It creates the same controller for each build, with its progress callbacks as parameters, and runs it on a separate thread of its own process.

kb4it build repo.json
  Workflow.build_website()
    1  Backend.stage_01_check_environment   folders, theme load, required templates, pipeline
       Theme.generate_sources()
    2  Backend.stage_02_get_source_documents
    3  Backend.stage_03_process_sources     pipeline.processor: properties, hashes, BuildPlan
    4  Backend.stage_04_process_theme       Theme.build()
    5  Backend.stage_05_compilation         pipeline.compiler, then Theme.build_page() per page
    6  Theme.post_activities()
    7  Backend.stage_06_deploy              pipeline.deployer
    8  Theme.post_deploy_activities()

Each stage logs [WORKFLOW] STAGE n=..., and its time shows as [PERFORMANCE] at DEBUG level. Errors are typed (ConfigError, ThemeError, CompilationError, KB4ITError) and caught once in KB4IT.run(), which turns them into exit status 1.

The cache is var/db/kbdict.json in each knowledge base. For every document it stores two blake2b hashes: one of the body without the title, one of the properties.

• A changed body recompiles the document.
• Changed properties recompile the document and every property and value page it appears on.
• A new or removed document refreshes the pages of its properties.
• A theme whose site_signature() changes, or a new KB4IT version, recompiles everything.

The Processor turns this into a BuildPlan: the documents to compile and the property pages to refresh. Compiled HTML is kept in var/cache/, so unchanged pages are copied instead of rebuilt.

A theme's logic/theme.py subclasses Builder. The core calls its hooks at the stages above and renders its Mako templates. Template lookup tries the theme's templates/ first, then kb4it/resources/common/templates/. See Create your own theme.