Traditionally, we think of directories as simple, nested folders. A path like /users/jane.doe/documents/q4-report.pdf is rigid and descriptive, but it tells you only one thing: where something is. But what if you need to know more? What if you need to find all documents owned by the 'engineering' team? Or all project assets with a 'draft' status?
With a conventional file system, these questions are surprisingly hard to answer. You'd need complex scripts to parse filenames or read internal file contents, a process that is slow, brittle, and doesn't scale.
This is where the paradigm shifts. What if your directory structure could be as rich and queryable as a database? With directories.do, it can. By attaching flexible metadata to every directory, you transform a simple hierarchy into an intelligent, searchable data store, unlocking powerful new workflows.
At its core, directories.do allows you to associate a flexible JSON object with any directory you create. This isn't just about adding tags; it's about enriching each entry with structured, meaningful context. This metadata becomes the foundation for building powerful, automated systems.
Consider the possibilities:
This metadata lives alongside your directory structure, turning it from a simple set of containers into a dynamic and queryable database.
Let's see how this works in practice. The power of directories.do is not just in storing this data, but in letting you find and act on it programmatically.
Instead of just creating an empty folder, you create an entry with all the information your application needs. Using the directories.do SDK, you can create a new project directory and embed its attributes directly.
import { Directories } from '@do-sdk/core';
// Initialize the Directories agent
const directoryService = new Directories();
// Create a directory for a new project report with rich metadata
const newReportDir = await directoryService.create({
path: '/projects/phoenix/reports/q3-performance',
metadata: {
projectId: 'proj-phx-001',
ownerId: 'user-id-12345',
status: 'draft',
reviewers: ['user-id-67890', 'user-id-11223'],
dueDate: '2024-10-31'
},
recursive: true // Automatically create /projects/phoenix/reports/
});
console.log('Successfully created directory:', newReportDir.path);
You've now created more than a path; you've created a queryable object within your system.
This is where the magic happens. Your directory is now a database. You can perform complex queries to find exactly what you need based on the metadata you defined.
Imagine you need to build a dashboard of all project reports currently in the 'draft' stage. Instead of traversing the entire directory tree, you can run a single, targeted query.
// Find all draft reports for the Phoenix project
const draftReports = await directoryService.query({
basePath: '/projects/phoenix/',
filter: {
'metadata.status': 'draft' // Query directly against your metadata fields
},
recursive: true
});
console.log(`Found ${draftReports.length} draft reports to review.`);
// Output: Found 5 draft reports to review.
This simple, expressive query replaces hundreds of lines of complex, custom logic. It's fast, scalable, and directly tied to the business logic you encoded in your metadata.
Once you can reliably query your directories, you can build powerful, automated workflows—or "agentic" workflows—that maintain your system. These are scripts or services that run in the background, using directory queries as triggers for action.
For example, a nightly agent could:
This turns a manual, error-prone process into a fully automated, reliable system managed entirely through the API.
By embracing the "directory as a database" model, you unlock several key advantages:
Stop thinking of directories as static containers. Start treating them as the dynamic, queryable databases they can be.
Ready to turn your directories into intelligent, automated data stores? Explore the directories.do API today and discover how to build smarter, more scalable applications.