Navigation Model

Indexes Explain What and When to Read

FISS/INDEX.md is the primary entry point. Indexes of individual areas are also named INDEX.md and reside within corresponding directories.

Every link to material or an area in an index file MUST be accompanied by a read condition: an explanation of when the referenced context is needed. In standard terminology, this rule is expressed as Read when... or Read always before....

Example root index for a project with multiple areas:

# Project Intellectual Space

- [Baseline Context](BOOTSTRAP.md) — Read always before beginning work on the project.
- [Domain Knowledge](knowledge/subject/INDEX.md) — Read when modifying business rules or working with domain concepts.
- [Project Architecture](knowledge/project/architecture.md) — Read when modifying system components or configuring the environment.
- [Current State](state/INDEX.md) — Read when risks, open questions, or temporary constraints may affect the task.

The label "Project Domain" only describes content. The read condition "Read when modifying business rules" helps decide whether the material is needed right now — this implements the “Make applicability visible” principle.

Following the “Separate navigation from content” principle, an index must remain concise: links, read conditions, and necessary navigational notes. Detailed content belongs in the referenced documents. This enables moving from general context to specifics on demand.

An Area Can Be a File or a Directory

An area is a thematically coherent unit in an intellectual space, such as project knowledge or open questions.

Form	When to Use	Naming Rule
Single file	The topic fits in one document	The filename is determined by the project
Directory with INDEX.md — composite area	The topic spans multiple documents	INDEX.md serves as the entry point
Directory without INDEX.md — container	Groups related areas together	Links to child areas reside in the enclosing index

For example, FISS/knowledge/ can serve as a container:

FISS/
├── INDEX.md
├── BOOTSTRAP.md
└── knowledge/
    ├── project/
    │   └── architecture.md
    └── subject/
        ├── INDEX.md
        ├── access.md
        └── notifications.md

In this example, the root index links to FISS/knowledge/project/architecture.md and FISS/knowledge/subject/INDEX.md. The index FISS/knowledge/subject/INDEX.md navigates its area materials. A separate FISS/knowledge/INDEX.md is not required.

Filenames of single-file areas and other substantive documents, like access.md, are determined by the project. The standard reserves the names INDEX.md for navigation points and BOOTSTRAP.md for the required baseline context.

All used areas must be reachable through navigation from FISS/INDEX.md. The index of a composite area must navigate to its materials and child areas; through a container, links point directly to nested areas. Every index link must include a read condition.

Expanding an Area

When a single file outgrows its scope, it can be replaced with a directory containing an index:

Before:                     After:
FISS/state/                 FISS/state/
└── open-questions.md        └── open-questions/
                                ├── INDEX.md
                                ├── payment-model.md
                                └── access-policy.md

When making this transition, update all incoming links. The new INDEX.md follows the same navigation rules as the root index.

Structure for Future Decomposition

In single-file areas, it is recommended to design a modular structure from the outset that can easily be divided into separate files as the document grows. This helps adhere to the “Start small” principle: starting with a simple single file while proactively preventing friction during future decomposition.

When the material within a file is organized into logically self-contained sections and subsections, each section becomes a natural candidate for extraction into a separate document or child area without having to untangle or rewrite intertwined text.

For example, an initial FISS/knowledge/project/architecture.md might contain:

# Frontend

## General Rules

- In `admin` and `front`, use TypeScript, not JavaScript.
- In TypeScript, do not use trailing semicolons `;`.
- Do not duplicate types between pages.
- Prefer a composable-first approach for backend interactions.

## Admin

- `admin` — Nuxt 4 SPA + `naive-ui`; SSR is disabled.
- `admin` SPA serves two hosts: admin host for `/admin` and business host for `/business`; do not add cross-host redirects that expose the admin host to business users.
- Use `admin/app/utils/apiFetch.ts` for backend requests, never direct `fetch`.

# Cache

## Redis Clients and DB Partitioning

- Redis is partitioned by responsibility:
  - DB0 / `snc_redis.token_store` / prefix `token:` — only refresh-token whitelist and auth/token storage.
  - DB1 / `snc_redis.app_cache` / prefix `cache:` — only application cache.
- Do not store application cache in DB0.
- Do not store auth/session/token data in DB1.
- Cache is not a source of truth. PostgreSQL and domain services remain authoritative.

## Application Cache Rules

- Every application cache entry must have an explicit TTL.
- Cache key must account for all request parameters and context values that can alter the response.
- Cache key must be deterministic and stable for equivalent requests.
- Never include raw user input, tokens, cookies, secrets, raw personal data, full URL with query strings, or request bodies in cache keys.
- If user input is unavoidable in a cache key in the future, normalize it first and prefer a safe hash/fingerprint over raw values.
- When adding or modifying a cache, specify an invalidation strategy in the same task.
- If invalidation is coarse-grained, document this explicitly and keep the TTL conservative.

When this file grows large, its clean modular structure allows it to be naturally split into, for example:

• FISS/knowledge/project/frontend/common-rules.md
• FISS/knowledge/project/frontend/admin.md
• FISS/knowledge/project/cache.md (or FISS/knowledge/project/cache/INDEX.md)