File structure and data dictionary
Folders and files, file formats and every field's definition.
What it explains and when it is useful
A file structure diagram shows how the project's files are organised. A file format specification describes the exact layout of any file the program reads or writes. A data dictionary defines every stored field.
When to use it: File structure: multi-file projects. File format: any program that reads or writes files (CSV, JSON, text). Data dictionary: any solution that stores data, in files or a database.
Worked example
Illustrative: PracticePal is a fictional project used throughout this guide.
Scroll sideways to see the whole diagram.
File format specification: usage report CSV
File name exports/usage_YYYY-Www.csv (ISO week), UTF-8, comma-separated, one header row, one row per room, rooms in code order.
| Column | Type | Example | Rule |
|---|---|---|---|
| room | text (2) | P5 | room code from ROOM |
| bookings | integer | 31 | confirmed + completed + no-show |
| minutes_used | integer | 780 | 30 × completed bookings |
| usage_pct | decimal (1 dp) | 39.0 | minutes_used ÷ 2,000 available minutes × 100 |
| no_shows | integer | 4 | status = no_show |
Data dictionary (extract)
| Table.field | Type | Size / range | Validation | Example |
|---|---|---|---|---|
| STUDENT.email | TEXT | ≤ 80 chars | ends @school.org; unique | m.l@school.org |
| STUDENT.password_hash | TEXT | ≈ 100 chars | never the plain password | scrypt:32768:8:1$… |
| STUDENT.role | TEXT | student | head | one of two values | student |
| ROOM.room_code | TEXT | 2 chars | P1–P6; primary key | P5 |
| BOOKING.start_time | TEXT (ISO datetime) | 07:30–17:00 start | on :00 or :30; Mon–Fri; not in the past | 2026-11-03T12:30 |
| BOOKING.loud | INTEGER | 0 or 1 | 1 only if ROOM.loud_allowed = 1 | 1 |
| BOOKING.status | TEXT | 5 values | confirmed, checked_in, completed, cancelled, no_show | confirmed |
| WAITLIST_ENTRY.state | TEXT | 5 values | waiting, offered, accepted, expired, withdrawn | waiting |
Notation and legend
| Symbol or part | Meaning |
|---|---|
| Folder icon | Directory |
| Page icon | File |
| Indent and lines | What is inside which folder |
| Italic note | The responsibility of the file |
Design decisions it communicates
A diagram earns marks when you explain the decisions it shows. In PracticePal's documentation these would each be one sentence:
- Data files sit outside the static folder so the web server never serves the database.
- Reports have one file per ISO week, so re-running a report for the same week replaces it.
- The status and state fields have fixed value lists, which the state diagrams explain.
Common mistakes
- A screenshot of a file explorer with no explanation.
- No format given for files the program reads, so a third party could not recreate them.
- A data dictionary without validation rules.
Checklist for your own version
Ticks are saved in this browser only, so you can use the list while you draft.