Early alpha · Local-first · No package publication or broad PHP compatibility claim
Home/Developers/Architecture

Architecture

Domain inward, applications outward

Nexus Scholar Core is shaped as a strict research workflow kernel. Apps, renderers, AI assistants, providers, and storage can make the system useful, but they must not become scientific authority by accident.

Architecture in one sentence

Core owns reconstructable scientific records; applications own experience, orchestration, persistence, and integrations. The dependency direction points inward, and the authority direction is explicit: suggestions and projections can support decisions, but they do not replace approved protocol content, evidence records, human decisions, or provenance.

The working product rule is: strict inside, simple outside, AI-assisted everywhere, human-authorized science.

Layer map

The repository is organized around a domain kernel with carefully separated supporting layers. The Core modules should not depend on UI frameworks, ASP.NET Core, EF Core, provider SDKs, storage SDKs, or concrete model clients. Those belong outside the domain boundary.

Dependency direction

Infrastructure and product surfaces depend inward. Core does not reach outward to hosts, providers, renderers, or AI SDKs.

Nexus Scholar Core scientific records and rules Applications CLI, desktop, web Infrastructure storage, providers, jobs Renderers Avalonia, web, CLI AI / plugins proposals, capabilities

UI portability

Core remains UI-free. UiContracts gives renderers a shared block language without giving UI code authority over scientific records.

Core records truth source, no UI UiContracts WorkspacePlan and research blocks Avalonia CLI Web Mobile

Authority pipeline

The architecture is easiest to understand as a pipeline of records. Each stage has a bounded job and a clear non-claim. Search observes. Deduplication structures duplicate evidence. Screening records human decisions. Full Text binds artifact bytes. Reporting derives checkable outputs. Bundles export verifiable packages. Provenance ties the history together.

Research workflow records

The modules are arranged so later stages cite earlier evidence instead of overwriting it.

Protocol approved plan Workflow compiled path Search raw trace Dedup evidence graph Screening human verdicts Full Text artifact bytes Provenance ledger Bundle

What must not collapse

The architecture exists to preserve distinctions that normal app workflows often blur.

AI suggestion not a decision Human decision actor, rationale, criteria App projection not Core authority Core record schema and digest bound Local path Raw-byte digest must be accepted by must be transformed into must cite

AI-assisted use cases

AI belongs in the architecture as assistance, not authority. A model can explain warnings, draft rationales, compare candidate records, suggest workflow blocks, or propose a command. A trusted application layer must validate that proposal, show its evidence, and require a human action when the action changes scientific state.

Assisted dedup review

AI can summarize why two records look similar. The merge decision remains a human gate over preserved evidence.

Dedup result candidate pair AI explanation proposal text Block action accept / reject Human merge or unresolved

Assisted screening rationale

AI may draft a rationale from evidence refs. A final screening decision still needs an identified human actor and criteria digest.

Candidate set locked input Criteria digest-bound AI draft suggested rationale Human verdict include / exclude

Use case catalog

These are the first public architecture use cases the project should make easy to understand. They are written as flows because architecture is only useful if it explains how real research work moves through the system.

Import evidence with warnings

A researcher imports RIS, BibTeX, or Scopus CSV exports. Core records the exact source-file digest, parser metadata, imported records, skipped rows, parser warnings, source-specific identifiers, and no-id candidates. The UI can show a warning block, but it cannot pretend warnings are resolved.

Review duplicate candidates

Deduplication clusters exact stable identifier overlaps automatically, but fuzzy title or no-id matches become review-required candidates. An app can show side-by-side comparison blocks and AI explanations, while the final merge/reject/unresolved action remains human-authorized.

Screen with human authority

Screening consumes a locked candidate set, applies criteria with a canonical digest, and records include, exclude, or needs-review decisions from identified human actors. AI suggestions may be cited, but they are not final decisions.

Attach full-text evidence safely

The Full Text contract starts with no-network, user-supplied or deterministic artifact evidence. The artifact identity is exact accepted bytes plus raw-artifact-bytes digest. Local paths, URLs, app rows, and download routes remain projections unless transformed into accepted Core records.

Export an audit bundle

A review bundle gathers governed records, artifact entries, manifests, and digest bindings for transport or replay. The bundle verifier reports structured findings before anything is trusted or overwritten.

Architecture rules for contributors

  • Domain projects do not reference EF Core, ASP.NET Core, UI frameworks, provider SDKs, storage SDKs, or concrete model clients.
  • NexusScholar.UiContracts stays renderer-neutral and has no Avalonia, web, mobile, CLI-renderer, provider, or AI SDK dependency.
  • NexusScholar.Avalonia.Blocks may render WorkspacePlan data, but it must not depend on Core domain projects.
  • Applications may display projections, but projections do not become Core authority without an accepted contract.
  • AI may propose explanations, rationales, block plans, or commands, but human-authorized decisions remain explicit.
  • Compatibility claims need fixture or comparator evidence; convenient similarity is not compatibility.