Documents Directory in a Mobile App — What It Is, Purpose and How to Organize Storage

What is the Application Documents Directory?

The documents directory is a specialized storage within the application sandbox, designed for permanent storage of user files. Unlike cache, files in this directory are considered important to the user: they are not deleted by the system when space is low, are preserved during app updates, and are backed up during device synchronization. On iOS, the Documents directory is part of the Sandbox container and is automatically included in iCloud backup. On Android, there is no direct equivalent — the equivalent is context.filesDir, which is also intended for permanent files but does not have a built-in backup mechanism.

The difference between the documents directory and Internal Storage on Android is minimal: both are located in the app sandbox, both are deleted upon uninstallation, both are inaccessible to other apps. The main difference is semantic: the Documents Directory assumes files are created or imported by the user, while Internal Storage may contain internal app files (databases, configurations). On iOS, the difference is more substantial: Documents is automatically backed up, while Library/Application Support is not. This affects the storage strategy: put only what the user would want to restore on a new device in Documents, and put internal data that the app can recreate in Application Support.

The sandbox architecture ensures that other applications cannot access your app's documents directory. On iOS, accessing other apps' Documents is impossible without jailbreak. On Android, root access allows reading any app's filesDir, so sensitive data (tokens, encryption keys) must be additionally protected using EncryptedSharedPreferences or EncryptedFile from the AndroidX Security library.

What Data is Stored in the Documents Directory

The documents directory should store data that is valuable to the user and should be accessible after restarting the app or restoring the device. Not all files are suitable for storage in this directory — the choice depends on the data type and usage scenario.

User Documents and Files

User files are the main content of the documents directory. These can be text documents created in an editor, images taken with the app camera, exported PDF reports, audio recordings, notes. Each such file is created by the user or at their request and must be accessible at any moment. On iOS, files from Documents are displayed in the system Files app, allowing the user to manage them through the standard file manager. On Android, there is no similar display — the app itself must provide an interface for viewing saved files.

Databases and App Settings

SQLite databases and settings files are usually stored near the documents directory but not inside it. On iOS, databases are placed in Library/Application Support, as they should not appear in the Files app and be backed up separately. On Android, databases are created by default in /data/data/<package>/databases/ via Room or SQLiteOpenHelper. If the database contains user content (notes, diary, financial records), it can be placed in filesDir to ensure system backup. Room allows specifying a custom database storage directory through the RoomDatabase.Builder callback.

val dbFile = File(context.filesDir, "user_database.db")

val db = Room.databaseBuilder<AppDatabase>(
    context,
    dbFile.absolutePath
).build()

Exported and Imported Data

Files that the user imports from other apps or exports from your app should also be saved in the documents directory. On iOS, import via UIDocumentPickerViewController automatically places a copy of the file in Documents when using the asCopy: true parameter. On Android, import via the SAF dialog also creates a copy of the file in the app sandbox. When exporting data (for example, creating a CSV file with contacts), save the file first in Documents/filesDir, and then offer the user to share it via Share Sheet. This ensures that even if the user forgets to save the file after sending, a copy remains in the app for later use.

How to Work with the Documents Directory on Android

On Android, the documents directory function is performed by context.filesDir. Additionally, the context.externalFilesDir directory on the SD card is available, but it does not guarantee data integrity. Let's look at the main techniques for working with these directories.

Accessing and Managing Files via filesDir

filesDir is the main directory for permanent app files on Android. It is located in the app sandbox and is completely deleted upon uninstallation. To get a File instance, use context.filesDir, which returns the path to /data/data/<package>/files/. To create and read files, use standard Java/Kotlin File operations or Context methods openFileInput() and openFileOutput(), which take a file name and return FileInputStream/FileOutputStream. The openFileOutput() method automatically creates the file in filesDir if it does not exist yet and allows specifying the access mode: MODE_PRIVATE (current app only), MODE_APPEND (append), or MODE_WORLD_READABLE (deprecated, not used since API 24+).

val fileName = "report.pdf"
val content = "PDF content".toByteArray()

context.openFileOutput(fileName, Context.MODE_PRIVATE).use { stream ->
    stream.write(content)
}

val bytes = context.openFileInput(fileName).use { stream ->
    stream.readBytes()
}

Storage Features on Android 10+

On Android 10+, the Scoped Storage model does not affect filesDir — full access to the app's own sandbox remains. All read and write operations inside filesDir do not require additional permissions. However, if you try to access another app's files via filesDir, you will get an exception. To share files, use FileProvider, which creates a temporary content URI to transfer a file to another app. FileProvider is declared in AndroidManifest.xml via the <provider> tag and configured in an XML path file. This is the standard mechanism for transferring files between apps, used, for example, when sending an image via Intent with ACTION_SEND.

How to Work with the Documents Directory on iOS

On iOS, the Documents Directory is part of the app's Sandbox container with special status. Files from this directory are automatically included in iCloud backup, displayed in the Files app, and preserved during app updates through the App Store.

Documents Directory and Backup

Automatic backup of Documents is a key advantage of iOS. When the user connects the device to iTunes or enables iCloud Backup, all files from Documents/ are copied to the backup. When restoring on a new device, the user gets all their files without additional actions. However, this advantage becomes a disadvantage if the app stores large amounts of data in Documents: backup time increases and iCloud storage may run out quickly. Therefore, Documents should only store files that the user really needs during restoration. Temporary files, cache, and recreatable data should be in Caches or Library/Application Support. Apple recommends excluding files that can be re-downloaded from the internet from backup using the isExcludedFromBackup attribute.

let fm = FileManager.default
let docsURL = fm.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first!

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "Note content"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive and Cross-Device Synchronization

iCloud Drive allows synchronizing files from Documents across a user's devices. To enable synchronization, the app should use the NSDocument or UIDocument APIs, which automatically manage versioning and conflict resolution. An alternative approach is using iCloud with CloudKit, which provides more flexible control over synchronization but requires configuration on the CloudKit Dashboard. When using iCloud Drive, ensure you correctly handle editing conflicts (merge or last-write-wins) and inform the user about synchronization status through the app interface. iCloud does not guarantee instant synchronization — the delay can range from a few seconds to several minutes depending on file size and connection quality. For critical data, use transactional writing and versioning so that in case of conflict, the previous version of the file can be restored.

Differences from Cache Directory and Best Practices

Choosing correctly between Documents Directory and Cache Directory determines the reliability of user data storage. An error in choice leads either to data loss (if important files are stored in cache) or to backup overflow (if temporary files are stored in Documents).

Best practices for using the documents directory include several key rules. First, always ask for user confirmation before deleting files from this directory. Unlike cache, deleting a document can lead to irreversible loss of user content. Second, implement file versioning: when overwriting an existing file, save the previous version with a _backup suffix or use Snapshot mechanisms. Third, provide the user with an interface for viewing, renaming, deleting, and exporting files from the documents directory. On iOS, files from Documents are automatically displayed in Files; on Android, you need to implement your own file manager or use third-party libraries.

Pay special attention to data migration during app updates. If the new version changes the file storage structure (for example, moves data from one subdirectory to another or changes the file format), implement a one-time migration on first launch after the update. Store the data schema version number in SharedPreferences and run migration if they do not match. Do not delete old files before migration completes — in case of failure, the user should not lose data. If migration involves format conversion (for example, switching from JSON to SQLite), save the original files as a backup in a separate directory with the migration date. The user should be able to revert changes through the app settings within the first 30 days after the update, as recommended by the Apple Human Interface Guidelines.