Skip to main content
Suchi’s filing trees are based on the Johnny.Decimal concept of areas and categories. Every document belongs to a category; uncertain filing remains in generated 40 System / 49 Inbox. Categories describe document kinds. Keep growing clients, properties, donors and family members in correspondents, not categories. Authoring v1 below defines the authoring and address contract and its adaptations from official Johnny.Decimal. The five built-in filing trees are CC0-1.0. They are unreviewed and are not compliance advice.

​
Filing systems and document addresses

Before the first taxonomy file with a top-level system header is applied, Suchi has one hidden original system. Unprefixed files keep the existing archive and paths; there is no enable-systems toggle or prerequisite configuration. The first prefixed import, for example system = "S01", offers two destinations:
  • Use this archive: name the original archive S01 and import into its existing tree, retaining documents, IDs, memberships and document grants.
  • Create separately: preserve the original under a distinct code (for example A00) and create S01 for the incoming tree. The preserved archive keeps its name.
Preview describes the destination and access changes. Apply commits introduction, tree, provenance and projection jobs atomically; stale or failed Apply leaves no partially introduced system. Afterwards a prefixed file targets its code, creating a new system if needed. An unprefixed file uses the captured selected system; unqualified CLI/session collection calls use the original system. Import cannot disable or collapse the system layer. Codes match exactly ^[A-Z][0-9]{2}$ (A00–Z99) and become immutable. Display names are editable, nonblank and at most 80 Unicode characters. First adoption or creation uses the file’s name; reimport preserves a locally edited system name. New systems initially admit only active instance administrators. Administrators grant direct user memberships separately from document permissions. There are no system roles, deletion, merge or document-transfer controls. Official AC.ID notation and multiple-system notation add an assigned, category-local ID layer. Suchi deliberately adapts that model: its filing address identifies a category and always has two components.
  • Before system introduction there is no address. The category code (21) already names the category, and its first digit places it in area 20–29.
  • After introduction, SYS.AC adds the permanent system code: category 21 in S01 is S01.21.
The numeric document ID is separate installation-global API identity. Documents 147 and 148 filed in S01/category 21 both project S01.21 while keeping distinct numeric URLs. Refiling document 147 to category 22 changes its projection to S01.22 without renumbering it; both category addresses remain resolvable while the categories exist. New versions and split children receive their own IDs. Addresses require an uppercase A00–Z99 system code and a two-digit category. Area-prefixed forms such as 20.21 are not addresses. Spaces, width variations, Unicode lookalikes, lowercase codes, and former three-component values such as S01.21.147 are invalid. A syntactically valid address still needs an existing category and system entry; document visibility is applied when the resulting Documents view runs. Selecting a system is Suchi’s simple “choose a filing cabinet” model, not a claim to reproduce every upstream JD convention. System entry and existing document ACLs are required; even admins cannot escape an explicit request or token system. Shared server administrators, host operators and backups remain trusted. This is application isolation over shared SQLite/CAS/FTS, not independent infrastructure, per-system encryption or evidence of professional independence. See Permissions for membership and delegated credentials.

​
Choose or change a tree

Settings > Archive configuration > Filing tree is a standalone workspace:
  • Ready-made compares solo, household, freelance, smb_billing and blank.
  • Build your own combines at most one focused set in each available decade. Solo and Household use 10–19, 20–29, 30–39 and 50–59; business sets may also use 60–69.
  • Import or export owns advanced TOML/HuML file operations.
Ready-made marks a card only when the active provenance matches that built-in. An imported custom tree leaves every card unselected—even if its file ID reuses a built-in name—while Current tree continues to show the live structure. Built-in trees deliberately stop at 60–69. Suchi reserves 40–49 for its generated System/49 Inbox and leaves 70–99 free for later operator additions. blank contains no user categories and needs explicit confirmation. Applying any reviewed tree or taxonomy import satisfies first-run archive setup. Solo and Household deliberately use only four user lanes and share their Money, Health and Home lanes. Their administration lane holds identity, insurance, vehicles, Memberships & associations (14), Education (15), Employment (16) and Travel (17). Freelance and Small business likewise omit generic Banking and client/customer/vendor/project “records” buckets. Their categories describe a specific document purpose or workflow stage instead. All four ready-made trees call their money-management lane Money, and each has a Bank & card statements category there. The plain label covers personal investments and borrowing as well as business expenses, tax working papers and payroll without suggesting a separate financial system. Each document should have one obvious home:
  • Use the most specific category. Purchases & warranties holds things you buy that have no more specific home: a vehicle’s purchase invoice goes to Vehicles, school fees to Education and a hospital bill to Medical billing.
  • Personal Travel holds tickets, boarding passes, itineraries, hotel and rental bookings and trip receipts. Visas stay in Identity; travel insurance stays in Insurance.
  • Statements go with the account they cover: bank and card statements to Bank & card statements, loan statements to Loans and investment statements to Investments.
  • Housing holds ownership and title documents, leases, rent, mortgage agreements, property tax and association charges. Loan statements and EMI schedules stay in Loans; income tax stays in Income tax.
  • Personal Medical billing is for provider charges, insurance claims and reimbursement records. Diagnoses, reports and discharge summaries stay in Medical records; medication instructions stay in Prescriptions.
  • Client payments and Customer payments hold payments received, remittances and overdue reminders. The invoice itself stays in Invoices out.
  • Freelance Briefs & plans is for project scope and planning. Signed legal terms and statements of work stay in Quotes & contracts.
  • Freelance Approvals & sign-off is for acceptance and completion evidence. Payment evidence stays with the relevant Money category.
  • Tax filings & acknowledgements holds submitted income, GST/sales and similar tax returns with their confirmations. Company, employment, pension and other non-tax submissions go to Corporate & regulatory filings.
Every built-in category has a one-line description of what belongs there and where a near neighbour’s documents go instead. The document model sees each category’s area, name and description. Filing trees carry no automations; write your own rules in Automations, in whatever language your documents use. Archives that applied an earlier version of a ready-made tree keep their categories until an administrator applies it again; the preview below shows each rename and addition, and categories that are no longer part of the tree keep their documents. Ready-made and composed changes always preview first. After Preview completes, the workspace moves focus to the review and scrolls it into view. The review shows the complete target tree, every category-name collision, and the number of live and recoverable documents using that category. A same-meaning built-in mapping updates the existing category row in place, preserving its ID and document references. Other mappings require a reviewed choice: replace the meaning in place, add the incoming category at the proposed free code in the same decade, or skip it. Apply is rejected if relevant state changed after Preview. Choose a .toml or .huml file, or paste its content. A chosen file selects its format from the extension; pasted content selects TOML or HuML from the required format header syntax. The File format control remains available for correction. Preview shows the name, story, version, user tree, generated structure, category additions and collisions. Changing input, file format or remaps requires another preview. If relevant destination state changes before Apply, Suchi preserves your input and asks you to preview again; unrelated system edits do not invalidate a preview. Validation checks supported structure, not domain suitability or reliable classification. Suchi never fetches remote taxonomy files or requires a catalog service.

​
Safe import and reimport

Only an initially unconfigured archive can replace its first filing tree, and only when no filed documents (including recoverable Trash) or dependent user configuration would be orphaned. Later imports add to the current filing tree; an empty archive alone is not permission to reset a chosen tree.
  • Same category code and name preserves the row and local description.
  • Different names at one code need explicit skip or an unused same-decade remap.
  • Imports never create, change or remove automations.
  • System destination, tree, last-import provenance and required jobs commit together; a failure leaves no partial import.
Built-in and composed transitions additionally support reviewed in-place replacement. Use Refile explicitly, or select it in the reviewed tree change, to run the target tree’s active automations and rebuild paths after Apply. Refile is not the taxonomy import itself. An ordinary custom taxonomy import adds to the current filing tree and is not a document-version operation.

​
Authoring v1

TOML is the default authoring and export format. HuML remains a first-class alternative with the same schema and behavior. YAML, unknown/duplicate keys, unsupported formats, wrong types and unsupported actions are errors. Validation is offline and bounded to 1 MiB. Files exported by v0.2 may still contain category keywords and seeds.automations; import ignores them and keeps the tree.
Required header: format, id, positive integer version, nonempty name, market, language, story. Author IDs match [a-z0-9][a-z0-9_-]*. Optional system names exactly one filing system; optional metadata is maintainer and license. Importing or exporting never implicitly licenses your configuration. Names are at most 80 Unicode characters, story 500, descriptions 240. Tree form requires explicit areas; areas = [] is a blank tree. Flat authoring shorthand uses flat = true and 1–9 categories instead of areas. Codes are 11–19 in order; explicit codes must match. Parsing expands it into an area tree; it does not select the separate runtime flat rendering mode. Database export may spell the tree as explicit areas rather than preserve the original shorthand. Never repurpose a category code within an author’s ID or call reordering compatible. User area starts are 10, 20, 30, 50, 60, 70, 80, 90. Categories belong to their area’s decade and never end in zero. Do not declare inbox, category-level protected system flags, 00–09 or 40–49: Suchi generates reserved structure after raw validation. The optional top-level system = "S01" is distinct and valid. Both reserved decades are forbidden remap destinations. The index is not a category or a selectable filing destination.

​
Export and provenance

Use --system S01 to select an existing system for unprefixed import or export. It must agree with a prefixed file. Only the first prefixed import accepts --existing-system-code A00 to preserve the original separately. Export creates a validated current snapshot with id = "archive", version = 1, not a claim that the combined archive equals its last imported file. Source identity, file version, byte SHA-256, schema version, source hash, and Suchi release version remain separate provenance. Equivalent HuML and TOML can have different hashes. Export contains the filing tree only. Automations, permissions, review history and documents need a complete backup. Only validated generated System/49 is removed from raw output. Legacy custom reserved categories, renamed system rows or a different Inbox produce an actionable error; Suchi does not hide or automatically renumber those records.

​
Generated filing index and paths

Before introduction the map is rendered/00-09 System index/00.00 archive.huml; afterwards each system has rendered/<SYS>/00-09 System index/00.00 archive.huml. It contains the current system code/name and tree/descriptions, with snapshot id = "archive" and version = 1. Generated System/49 is implicit. It is a managed area/category map, not the original authoring file, the upstream JD register of assigned ID folders, a document inventory or backup. Do not edit it in place. Committed filing-tree changes queue a durable taxonomy_index refresh. Server startup also queues a refresh per system to recover missing/stale indexes. Jobs build current state when they run and replace the file atomically. Failure preserves the last complete index and uses normal retries/dead-job reporting. A successful import with pending work does not mean the physical file has refreshed; CLI-only imports need the server to process jobs. No document row or CAS blob is created. After introduction, document projections are rooted at rendered/<SYS>/ using the immutable code, not the editable display name. The default filing-tree layout for an illustrative already-returned document is:
Default JD and runtime-flat filenames use created date, then added date, otherwise undated, title, and the independent __<doc_pk> suffix in both single and multi-system archives. Explicit templates retain relative behavior; jd.system.code, jd.system.name, and category-level jd.address are available. Because jd.address can repeat, a collision-safe explicit layout must also use doc_pk, or asn where that layout already requires a unique archive serial number. Renaming a system does not move its root. New and edited templates cannot carry a file extension: preview, create, and update reject one because Suchi appends the linked file’s own, .pdf for the searchable copy and otherwise the original’s type (.jpg, .eml, .docx, …). An unknown type gets none. Templates also cannot escape the enforced system root or occupy a managed index. First introduction queues render-only moves for existing live documents. Durable move journals recover interrupted publication at the current target; cleanup removes only a verified document CAS link or proved-managed legacy index, never arbitrary user files. Only the original system’s index writer removes the old root index, after publishing its named replacement. Startup does not rewrite the whole filesystem. Stable v1 repairs the absolute two-shard links emitted before v0.1.0 when their blob hash still belongs to that document; unrelated links remain untouched. Use suchi refile --system S01 --skip-automations for render-only work without rerunning OCR or classification.

​
Category API

GET /api/jd/categories/ lists ordinary categories with area labels and optional q and area filters within the selected system. Category system remains a protected-row boolean; system_code identifies its filing system. Set a document’s category with {"jd_category_id":17}: the row must belong to that document’s system, and runtime row IDs differ from portable category codes. Category addresses resolve through GET /api/jd/resolve?address=S01.13; the response opens a filtered Documents view while numeric document IDs and URLs remain exact identity. Mobile uses ordinary bound-system APIs; taxonomy administration is session-admin web/CLI. See API and Automations.
Johnny.Decimal is a trademark of Coruscade Pty Ltd. Suchi is independent and is not affiliated with or endorsed by them.