| name | fgts-naming-convention |
| description | FGTS — From General To Specific. A deterministic, scope-descending identifier system for files, variables, configs, and APIs. Makes names sortable, groupable, and self-documenting. |
FGTS — From General To Specific
A deterministic, scope-descending identifier system for files, variables, configs, and APIs · v1.0
Core Principle
Every identifier is a path through a conceptual namespace, moving from the broadest context down to the most specific detail. Reading left to right is like zooming in on a map — each segment narrows the scope of the one before it.
This makes names sortable, groupable, and self-documenting without external tooling. The convention applies uniformly to filenames, variables, config keys, API routes, and database fields.
Segment Anatomy
<domain>_<system>_<entity>_<attribute>_<qualifier>
| Position | Level | Role | Examples |
|---|
| 1 | Domain | Top-level context | net auth db ui cfg |
| 2 | System | Subsystem / module | flow session query form cache |
| 3 | Entity | Object / resource | iface user table input entry |
| 4 | Attribute | Property / metric | bytes count ts id name rate |
| 5 | Qualifier | Direction / state / variant | in out prev max raw err |
Canonical example:
net_flow_iface_bytes_in
│ │ │ │ └─ qualifier : inbound direction
│ │ │ └─────── attribute : byte count
│ │ └───────────── entity : network interface
│ └────────────────── system : NetFlow pipeline
└────────────────────── domain : network monitoring
Segments are separated by _ (snake_case). Use - (kebab-case) for filenames and URLs. Omit trailing segments when specificity is unambiguous in context.
Rules
-
Left-to-right specificity is mandatory. Never place a narrower segment before a broader one. auth_session_user_id is valid; id_user_session_auth is not.
-
All lowercase, no spaces. Snake_case for code identifiers; kebab-case for file paths and URLs. Mixed case within segments is forbidden.
-
Use abbreviations consistently. Establish a project-level glossary (e.g. ts = timestamp, cnt = count, cfg = config). Never mix abbreviated and full forms of the same word.
-
Omit obvious segments. Inside the auth module, session_id is sufficient — prepending auth_ is redundant. Apply the innermost-scope rule.
-
No verbs in data names. Verbs belong in function/method names. Data identifiers describe what a thing is, not what you do with it. db_query_result_rows not db_get_query_rows.
-
Qualifiers are the last resort. Only add a Level 5 qualifier when the attribute is genuinely ambiguous without it. bytes_in vs bytes_out is valid. count_final is a smell.
-
Plural only at the entity level. net_flow_ifaces_count — the entity (ifaces) is plural because it's a collection. Attributes and qualifiers stay singular.
Examples by Context
| Context | FGTS Identifier | Meaning |
|---|
| Variable | net_flow_iface_bytes_in | Inbound byte count for a specific interface in the NetFlow pipeline |
| Config key | db_cache_ttl_sec | TTL in seconds for the database cache layer |
| Filename | auth-session-token-refresh.py | Script for refreshing session tokens in the auth subsystem |
| API route | /net/flow/iface/{id}/bytes | REST endpoint exposing byte metrics for an interface |
| DB column | auth_session_user_id | FK to user within the session table of the auth schema |
| Metric | net_flow_iface_pkt_drop_rate | Packet drop rate per interface in the flow domain |
| CSS variable | --ui-form-input-border-focus | Border color token for focused state of form inputs |
| Env var | DB_REPLICA_HOST_PRIMARY | Hostname of the primary replica (SCREAMING_SNAKE) |
Good vs. Bad
✗ Violations
getFlowBytesIn # verb prefix + camelCase — wrong casing, wrong order
in_bytes_iface_net # reversed specificity — qualifier before domain
iface_bytes # missing domain context — collides across systems
netFlowIfaceByteIn # camelCase — reserved for method/function names
✓ Correct
net_flow_iface_bytes_in # all five levels, left-to-right, snake_case
net_flow_iface_bytes_out # parallel structure — differs only at qualifier
net_flow_iface_pkt_cnt # abbreviation used consistently per glossary
flow_iface_bytes_in # domain omitted — valid inside a net-scoped module
net-flow-iface-report.md # kebab-case for filename; same hierarchy
Starter Abbreviation Glossary
| Abbrev | Full form | Abbrev | Full form |
|---|
ts | timestamp | cnt | count |
cfg | config | pkt | packet |
iface | interface | err | error |
sec | seconds | ms | milliseconds |
max / min | maximum / minimum | prev / cur | previous / current |
req / res | request / response | raw | unprocessed value |
FGTS Naming Convention · From General To Specific · v1.0 · 2026
