Reference Map

Reference Map

Use this page to move from an operational question to the right Wiki guide, versioned repository document, executable interface, or source module. It maps Pizarra 1.1.41 as published; the versioned repository remains authoritative when Wiki prose and deployed code differ.

Find an answer by goal

Goal	Start in the Wiki	Versioned repository reference
Understand what the suite solves	Why Pizarra	README
Learn the hub, endpoints, state, and trust boundaries	Concepts and Architecture	Architecture
Build a safe loopback installation	Start Here	Quick start
Design teams, groups, projects, and applications	Organization Model	Configuration and CLI
Send work and handle offline delivery	Messaging and Inbox	Wire protocol
Create, assign, note, or close tasks	Tasks	CLI
Build branches, joins, gates, and recovery	Workflow Engine	Workflows
Operate from a terminal	Tiza CLI and Console	CLI
Operate from a browser	Web Console	Web console
Integrate with HTTP	Web API	Web API
Implement a native client	Native Wire Protocol	Wire protocol
Configure any process	Configuration Reference	Configuration
Select local, push, dial, or inbox-only delivery	Deployment Topologies	Architecture and Operations
Exchange small verified artifacts	Files and Transfers	Security and CLI
Back up, restore, or update endpoints	Backup Restore and Updates	Operations
Supervise and troubleshoot a deployment	Operations Runbook	Operations
Review threats and deployment controls	Security Model	Security model and policy
Validate a release	Testing and Release Validation	Testing
Decide whether current constraints fit	Limitations and Compatibility	Limitations
See every published interface	Gallery and this page	Documentation index

Program map

Program or mode	Primary interface	Responsibility	Local durable state
pizarra	pizarra [--config PATH] [--migrate-only] [--version]	Hub, authentication, journal, routing, retries, organization, tasks, workflows, watch streams	Hub configuration and store
tiza one-shot	tiza [--config PATH] <command-or-destination> ...	Messages, inbox, registries, tasks, workflows, files, backup, restore, fleet	Configuration only
tiza chat	Interactive commands and live feed	Human terminal supervision	Shell-side command history
tiza daemon	Push listener or reverse-dial endpoint	Session watchdog, deduplicated injection, activity, endpoint update	Per-team receipt state
pzweb	Browser and /api/	Authenticated HTTP adapter, eight browser views, SSE bridge	No copy of hub state; assets load at startup

All three binaries report release 1.1.41. Use tiza ver to compare the local suite with the hub and tiza fleet to inspect endpoint versions.

Tiza command map

Area	Canonical command family
Direct and broadcast messaging	tiza <team> ..., tiza all ..., tiza @<group> ...
Durable inbox	tiza inbox, --keep, --all
Human console	tiza chat, tiza chat --plain
Tasks	`tiza task add
Workflows	`tiza wf create
Workflow editing and history	`tiza wf insert
Teams and hierarchy	tiza team ..., tiza tree
Groups and projects	tiza group ..., tiza project ...
Applications	tiza app ...
Delivery context	tiza header ...
Shared files	`tiza share
Holds and fleet	tiza hold, tiza fleet, tiza update
Backup and restore	tiza backup, tiza backup verify, tiza restore
Offline help and version	tiza --help, tiza manual, tiza wf help, tiza --version

Use the versioned CLI reference for exact argument order, optional flags, authority, and state restrictions.

Browser route map

Concern	Read routes	Mutation routes
Live and durable messages	/api/feed, /api/messages, /api/message/<seq>	/api/message
Inbox	/api/inbox	/api/inbox/ack
Tasks	/api/tasks, /api/task/<id>	/api/task and task state/note/assign/delete routes
Workflows	/api/workflows, /api/workflow/<name>, history	Workflow create, edit, lifecycle, recovery, undo, restore, clone routes
Organization	Teams, groups, projects, applications and cards	Validated team/group/project/application route families
Shared files	/api/files, /api/download	/api/upload, /api/shared/delete
Operations	/api/fleet, /api/version, /api/header, /api/help	/api/backup, /api/fleet/update, /api/header

Every asset and route requires source admission, exact Host, and Basic authentication. Every mutation additionally requires exact Origin, JSON media type, X-Pizarra: 1, and an exact route-specific object. See Web API.

Native command map

The public protocol groups commands by responsibility:

Area	Native commands or families
Messages and cursors	send, inbox, ack, recent
Discovery and live state	teams, watch, ver, capability discovery
Durable work	task, workflow
Organization and context	team, group, project, app, header
Files	put, get
Fleet and recovery	fleet, backup, update
Endpoint transport	deliver, ping, dial

All ordinary requests use one credentialed JSON object and one response line. watch and dial become streams. See Native Wire Protocol before building an integration.

Durable state map

Paths are relative to [store] dir unless noted.

Path	Authority and purpose	Backup note
.pizarra-hub.lock	Persistent mode-0600 inode for the exclusive hub/restore lifetime lock	Metadata; deliberately not replaced by restore
messages.jsonl	Durable message journal	Included in built-in backup
state.json	Next sequence, delivery marks, inbox cursors	Included
tareas.json	Authoritative tasks and notes	Included
workflows.json	Authoritative workflow cards and notification outbox	Included
wfhistory/*.json	Newest 30 pre-change snapshots per workflow	Not included; retain separately if required
org.sqlite	Teams, groups, projects, applications, relations, history	Included through SQLite online backup
work.sqlite	Task projection and history	Included through SQLite online backup
apps.sqlite	Compatibility and migration database	Included through SQLite online backup
appdocs/*.md	Legacy manual migration material, if retained	Not included; retain separately if required
backups/	Default built-in backup destination	Protect as credential-bearing data
releases/	Canonical private endpoint artifacts selected by VERSION	Not included; regenerate from the exact commit or protect separately
/mnt/pizarra-shared (illustrative external mount)	Shared exchange selected identically by hub and pzweb	Reference only is present in hub config; content requires a separate coordinated snapshot
Tiza daemon state path	Last injected sequence per hosted team	Protect separately on each endpoint host

Do not edit live store files or remove the persistent lock inode. If SQLite is unavailable, corrupt, unupgradeable, or cannot be projected completely, the hub refuses to start rather than serving a partial legacy registry.

Source map

Program entry points

Source	What to inspect there
src/pizarra.pas	Hub startup, authenticated command dispatch, delivery, watch streams, registry coordination, backup and fleet handlers
src/tiza.pas	One-shot CLI builders, daemon behavior, command dispatch, files, backup/restore, fleet operations
src/pzweb.pas	HTTP perimeter, route validation, JSON projection, SSE, assets, connection limits

Shared implementation units

Unit	Responsibility
pzconfig	INI loading, identity resolution, organization records, delivery-envelope construction
pzproto	Wire constants, message structures, JSON builders and parsers, line limit
pznet	TCP server/client plumbing, deadlines, shutdown, sent-versus-not-sent reporting
pzstore	Message journal, sequence allocation, delivery marks, inbox cursors, compaction
pztasks	Atomic task persistence, task rules, notes, workflow links
pzworkflow	Dependency graph, transitions, recovery gate, durable notice outbox, reconciliation
pzdb	Runtime-loaded SQLite registries and history
pzlayout	Canonical Unix paths, secure first-run skeleton, durable fsync helpers, and the hub/restore lifetime lock
pzchat	Interactive console, watch reconnect, input editor, command dispatch
pztmux	Managed terminal sessions, bracketed-paste delivery, activity capture
pzshare	Shared-file naming, collision handling, local copy limits
pzupdate	Endpoint artifact download, digest check, staged install, rollback
pzsha256	Streaming SHA-256 implementation
pzansi, pzbox	Terminal color gate, display width, tables, cards, and plain-output behavior
pzmanual	Embedded offline quick guide
pzlog	Human-readable append-only operational log
pzver	Shared suite version and comparison

Browser assets

The bundled application is under web/apps/. The files are preloaded into pzweb memory at startup; changing them requires a pzweb restart. The main functional modules cover the application shell, live feed, history, inbox, files, transfers, task and organization management, and workflow visualization.

Build and release map

File or target	Purpose
configure	Validate toolchain and paths; write ignored config.mk
Makefile	Release/debug/tiny builds, checks, install, test, and atomic publication to the absolute /var/lib/pizarra/releases default
systemd/	Example units for separate hub, endpoint, and web accounts
ci.yml	Node/npm-free configure, release/version and debug builds, plus isolated bootstrap, private-config, group-policy, shared-copy, release-layout, and retirement harnesses
CHANGELOG.md	Published release history

make test currently builds and checks version entry points. It is not the full integration matrix described in Testing and Release Validation.

Limits at a glance

Boundary	Pizarra 1.1.41 value
Native JSON line	1 MiB
Message file body	256 KiB
Native file chunk	512 KiB
Complete transferred file	10 MiB
HTTP mutation body	64 KiB
Web static asset / full tree	2 MiB / 32 MiB
HTTP connections	256 global, 64 per source
SSE feeds	16 per source
Browser Activity retention	300 messages per tab
Message and inbox page	Maximum 200 entries
Workflow milestone title	120 characters
Workflow proof/error/fix text	4096 characters
Workflow snapshots	Newest 30 per workflow
Consumed messages retained at startup compaction	Recent window of 5,000, plus all pending/unconsumed messages
Endpoint update artifact	128 MiB

These are safety boundaries, not benchmark-backed capacity targets. Pizarra 1.1.41 publishes no fleet, workflow, task, or throughput scale target.

Outcome and continuity map

Signal	Interpretation
ok:false	Definite validation, authority, or state rejection
queued:true	Message is durable and awaits endpoint delivery. NOT a statement that the endpoint is unreachable: a dial-in team reports this on every message, because its acknowledgement arrives later on the reverse channel. The reply's note says which case it is
not_sent	Adapter did not write the request; retry is safe
unknown	Request was written but result is not known; inspect state
applied_stale	Mutation applied, refreshed projection unavailable; reload
gap event	Stream continuity cannot be certified; reload durable state
Sequence jump without gap	Normal for a scoped viewer
SQLite unavailable	Hub startup fails; repair the mandatory authoritative registry before serving work

Version and documentation rule

Reference pages in this Wiki describe Pizarra 1.1.41. When changing or upgrading a deployment:

1. compare local, hub, and endpoint versions;
2. review the repository changelog;
3. consult the versioned source document for the affected interface;
4. re-run the build and integration checks appropriate to that change; and
5. update operational documentation rather than relying on an older Wiki example.

Continue with FAQ for common questions or Limitations and Compatibility for the boundaries that should shape an architecture decision.