# Architectural Overview Audience: People evaluating, explaining or operating NovusLens ## s00 · What NovusLens brings together · Architectural Overview Before changing a service, you need to know which teams, systems and suppliers it depends on. NovusLens brings them together so you can examine dependencies, question the evidence and decide what needs attention. Here is how it works. Sources: - apps/docs/content/architecture/how-it-works.mdx ## s01 · Bring in a file · Import company records First, bring in a company record, such as an organisation chart. File imports read the supported format and extract those relationships. They also save the original file in Postgres, the database. Keeping the source means someone can later check where a relationship came from. Sources: - apps/docs/content/architecture/how-it-works.mdx ## s02 · Build the map · Build a view of teams and dependencies The extracted relationships are recorded in an ordered log of structural changes. Projection is the worker that reads those changes and builds database views in Postgres. The web application can then display them as an organisation map. Sources: - apps/docs/content/architecture/how-it-works.mdx ## s03 · Connect the wider picture · Connect teams to their infrastructure Next, add the technology those teams depend on. Cloud ingest reads supplied cloud inventories, Terraform state and datacentre exports and uses tags and labels to connect systems to the organisation. The original exports stay in Postgres. Their extracted relationships follow the log and Projection into the same view. This step reads exports, rather than discovering live cloud resources. Sources: - apps/docs/content/architecture/how-it-works.mdx ## s04 · Add operational evidence · Compare the documents with operational evidence Documents describe an arrangement. Operational records help you examine what happens in practice. Source acquirers are connectors that read supported systems, including Jira, Prometheus, GitHub and PagerDuty. A separate corrector job compares fresh readings with recorded relationships and records observations or findings. Projection makes these available in Postgres. Supporting evidence remains available for investigation. Sources: - apps/docs/content/architecture/how-it-works.mdx ## s05 · Add reported declarations · Include AI agents and their responsibilities AI agents also take part in the work. Declarations describe their capabilities, reported authority and responsibility. Acquirers read these declarations from imports and enrolled feeds. They keep the source records in Postgres and record the extracted relationships. Projection adds these to the organisation view. Reports of what agents actually did enter through a separate connection. Sources: - apps/docs/content/architecture/how-it-works.mdx ## s06 · Add signed activity · Receive signed activity reliably That connection is the signed intake. It checks enrolment, signatures and permitted record types. Before returning a receipt, it saves the activity batch, its evidence and a pending delivery in one database transaction. A delivery worker later reads pending deliveries and publishes references to the structural log. Projection reads the log to update the views. Sources: - apps/docs/content/architecture/how-it-works.mdx ## s07 · Add written context · Keep the explanations as well as the relationships Relationships alone cannot explain a policy or an operating procedure. The internal Knowledge library holds statements from policies, runbooks and other documents, linked to their sources. It stores these entries in Postgres too. The Reasoning service can retrieve permitted knowledge alongside structural records. This gives an answer written context, such as how a team describes its responsibilities. Sources: - apps/docs/content/architecture/how-it-works.mdx ## s08 · Use the records · Calculate measurements from evidence The same evidence supports measurements. Acquirers derive readings from their sources. Projection stores committed observations and values for parts of the organisation. When requested, Reasoning calculates assessment scores from stored evidence, including Complexity, Agility and Recoverability. Missing evidence remains visible. Reasoning also writes knowledge contributions, proposals and audit records directly to Postgres. Sources: - apps/docs/content/architecture/how-it-works.mdx ## s09 · Follow a question · Ask a question about those records Now someone can ask which teams and systems a service depends on. The browser sends the question through the web server to Reasoning. Reasoning checks access and retrieves permitted relationships, evidence and knowledge from Postgres. When a task needs a language model, Reasoning sends relevant context to a configured HTTP endpoint. That model can run locally or with an external provider. Sources: - apps/docs/content/architecture/how-it-works.mdx ## s10 · Return an answer · Return an answer people can check The model returns its response to Reasoning. Reasoning assembles an answer with citations and sends it through the web server to the browser. The person can follow those citations to inspect the supporting evidence. This lets someone examine the basis for an answer before deciding what to do. Sources: - apps/docs/content/architecture/how-it-works.mdx ## s11 · Update the recorded account · Record a reviewed change People can also browse relationships directly: the web server reads permitted views from Postgres without calling a model. Actions such as reviewing a proposal go through Reasoning. When a person confirms a structural change, Reasoning records it in the log and Projection updates the database view. The next person sees the revised relationships. People remain responsible for action. Sources: - apps/docs/content/architecture/how-it-works.mdx ## s12 · Application infrastructure · The infrastructure underneath These components need somewhere to run and a way to communicate. Docker runs the web server, Reasoning, Projection, Postgres and Mycelium sidecars in containers connected by a private network. Mycelium provides shared coordination and the ordered log used for structural changes. Postgres provides persistent database storage. Sources: - apps/docs/content/architecture/how-it-works.mdx ## s13 · The complete architecture · How the components work together Here is the complete architecture. Sources connect through imports and acquirers. Original evidence stays in Postgres. Structural changes reach Projection through the log and become views of the organisation. Signed activity is stored before later delivery. Reasoning retrieves knowledge and evidence, calculates measurements and calls models when needed. The web application displays relationships and cited answers. Confirmed changes update those relationships. Together, they help people understand dependencies and examine the evidence behind decisions. Sources: - apps/docs/content/architecture/how-it-works.mdx