Skip to content

Finnest — Internal Documentation

Confidential

This documentation contains commercially-sensitive architecture detail and decision history. Internal distribution only.

Finnest (commercial: Hexis) is an AI-native, multi-industry workforce management platform for Australian employers in compliance-heavy industries.

This site is the single top-down reference for understanding what Finnest is, how it is built, and why it is built that way. It is organised around the Arc42 architecture-documentation template and is intended for a semi-technical audience: product-level stakeholders, new engineers, auditors, and investors' technical advisors.

Start here

  • New? Read in this order

    1. Introduction & Goals — what is Finnest and why does it exist? (~5 min)
    2. System Context — what does it talk to? (~5 min, 1 diagram)
    3. Building Blocks — what are the parts? (~10 min)
    4. You now have a defensible mental model. Drill wherever you want.

  • Looking for something specific?

  • Interactive architecture browser →

    Click-through C4 browser for every system and view. Drill from context down to containers, dependencies, and decisions. Generated from one Structurizr DSL source on every deploy, so the static Mermaid embeds on this site and the interactive views cannot drift.

    For local editing with live reload (Structurizr Lite): docker compose up structurizr → http://localhost:8080

  • Code-level reference

    For the engineer audience — module-by-module, function-by-function Elixir documentation is published at /api/ (ExDoc output, integration pending STORY-F-004 tail).

What this documentation covers

Layer Audience Pages
Business & goals Any stakeholder Arc42 §1–§2
System context Semi-technical Arc42 §3
Solution strategy Semi-technical Arc42 §4
Building blocks Semi-technical + engineers Arc42 §5
Runtime & deployment Engineers + SREs Arc42 §6–§7
Crosscutting concerns Engineers Arc42 §8
Decisions (ADRs) Engineers + auditors Arc42 §9 + full ADR index
Quality & risks Stakeholders + auditors Arc42 §10–§11
Glossary Everyone Arc42 §12

How this documentation is maintained

  • Markdown in git. Every page is a .md file in the finnest-planning/ repository. There is no separate wiki system.
  • Zero drift. ADRs, brainstorms, PRDs, stories, and architecture documents are symlinked into this site from their canonical locations. When you update an ADR, this site rebuilds automatically.
  • Diagrams from code. The C4 diagrams on this site are generated from a single Structurizr DSL file — docs/structurizr/workspace.dsl. Interactive browser and static exports are always in sync because they share the source.
  • Open source only. MkDocs-Material (MIT), Mermaid (MIT), Structurizr (Apache 2.0), Arc42 (Creative Commons), ExDoc (Apache 2.0). No commercial SaaS documentation platform; no vendor lock-in.

See docs/README.md for build, serve, and deploy instructions.

Origin of this site

This documentation system was designed in brainstorm-13 as the answer to: "What is the best way for a semi-technical reader to understand Finnest top-down — logic, architecture, and technical?"