# What Is the Purpose of the src Directory in macro-inc/macro?

> Discover the purpose of the src directory in macro-inc/macro. Learn how it holds Rust source code and enables Cargo to compile project microservices effectively.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: internals
- Published: 2026-08-15

---

**TLDR:** The `src` directory houses the Rust source code for each crate in the macro-inc/macro workspace, serving as the required location for entry points like [`lib.rs`](https://github.com/macro-inc/macro/blob/main/lib.rs) and [`main.rs`](https://github.com/macro-inc/macro/blob/main/main.rs) that enable Cargo to compile the project's microservices.

The **macro-inc/macro** repository organizes its Rust code as a Cargo workspace where the **purpose of the `src` directory** is to serve as the conventional container for all source files in each crate. Located within every service folder—such as `document-storage-service` or `search_service`—the `src` directory provides the mandatory entry points that the Rust compiler requires to build the project's independent microservices.

## Standard Rust Layout in the macro-inc/macro Monorepo

The repository's top-level [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) defines a workspace that aggregates dozens of independent crates, including `document-storage-service`, `search_service`, `email_service`, `entity_mentions`, and `authentication_service`. Within each crate directory, the `src` folder contains the implementation code, following Rust's mandatory convention for source file placement.

### Workspace Configuration and Compilation

Cargo uses the workspace definition to locate member crates, and within each crate, the compiler expects source files to reside under `src`. This structure allows the workspace to compile services in isolation while maintaining cohesive dependency management across the entire codebase.

### Entry Points and Module Resolution

Rust's module system relies on specific entry point files within `src` to determine how a crate is built:

- **[`src/lib.rs`](https://github.com/macro-inc/macro/blob/main/src/lib.rs)**: Defines the library interface for crates like `entity_mentions` and `document-storage-service`, exposing structs and functions to other workspace members via `pub` visibility.
- **[`src/main.rs`](https://github.com/macro-inc/macro/blob/main/src/main.rs)**: Present in binary crates, defining the executable entry point that imports the library or implements standalone application logic.

Additional modules are declared using `mod foo;`, which instructs the compiler to locate the implementation in [`src/foo.rs`](https://github.com/macro-inc/macro/blob/main/src/foo.rs) or [`src/foo/mod.rs`](https://github.com/macro-inc/macro/blob/main/src/foo/mod.rs) relative to the crate root.

## Implementation Examples from the macro-inc/macro src Directories

The `src` folders contain concrete implementations for database access, HTTP handlers, and background workers across the microservices.

### Database Operations in entity_mentions/src/lib.rs

The `entity_mentions` crate defines data models and persistence logic in its library entry point. The `create_mention` function demonstrates async database insertion using **sqlx**:

```rust
use sqlx::query_as;

#[derive(Debug, sqlx::FromRow)]
pub struct EntityMention {
    pub id: i64,
    pub source_entity_type: String,
    pub source_entity_id: i64,
    pub target_entity_type: String,
    pub target_entity_id: i64,
    pub created_at: chrono::NaiveDateTime,
}

/// Insert a new mention into the database.
pub async fn create_mention(pool: &sqlx::PgPool, mention: EntityMention) -> sqlx::Result<()> {
    sqlx::query!(
        r#"
        INSERT INTO entity_mentions
            (source_entity_type, source_entity_id,
             target_entity_type, target_entity_id, created_at)
        VALUES ($1, $2, $3, $4, $5)
        "#,
        mention.source_entity_type,
        mention.source_entity_id,
        mention.target_entity_type,
        mention.target_entity_id,
        mention.created_at,
    )
    .execute(pool)
    .await?;
    Ok(())
}

```

### HTTP Handlers in search_service/src/handlers.rs

The search service implements HTTP endpoint logic using **Axum** extractors. The `search` function accepts application state and JSON payloads, delegating to the internal `SearchService`:

```rust
use axum::{extract::State, Json};
use crate::service::SearchService;
use crate::models::SearchQuery;

pub async fn search(
    State(search): State<SearchService>,
    Json(payload): Json<SearchQuery>,
) -> Json<SearchResult> {
    let result = search.perform(&payload).await;
    Json(result)
}

```

### Background Workers in email_service/src/worker.rs

Long-running background tasks reside in [`src/worker.rs`](https://github.com/macro-inc/macro/blob/main/src/worker.rs). The `start_worker` function implements an infinite loop with timed polling, typical for email queue processing:

```rust
use tokio::time::{sleep, Duration};

pub async fn start_worker(pool: sqlx::PgPool) {
    loop {
        // Pull pending emails from DB, send them, mark as sent…
        // …
        sleep(Duration::from_secs(30)).await;
    }
}

```

## Critical Source Files Across the Workspace

The following `src` directories house core functionality for their respective services:

- **[`document-storage-service/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/document-storage-service/src/lib.rs)**: Implements the core API for document storage and retrieval, handling persistence logic and storage interactions.
- **[`authentication_service/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/authentication_service/src/lib.rs)**: Contains user authentication flows, password verification, and JWT token management systems.
- **[`search_service/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/search_service/src/lib.rs)**: Defines the search indexing logic and query processing algorithms exposed to the application's API layer.
- **[`email_service/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/email_service/src/lib.rs)**: Manages inbound parsing and outbound sending workflows for email processing.

Each of these files lives under its crate's `src` directory, maintaining strict separation of concerns between the workspace's microservices.

## Summary

- The `src` directory in **macro-inc/macro** follows the standard Rust convention, housing all source code for each workspace crate.
- **[`src/lib.rs`](https://github.com/macro-inc/macro/blob/main/src/lib.rs)** serves as the library entry point exposing public APIs, while **[`src/main.rs`](https://github.com/macro-inc/macro/blob/main/src/main.rs)** defines binary executables for runnable services.
- Sub-modules are organized within `src` using the `mod` declaration, allowing the compiler to resolve [`src/foo.rs`](https://github.com/macro-inc/macro/blob/main/src/foo.rs) or [`src/foo/mod.rs`](https://github.com/macro-inc/macro/blob/main/src/foo/mod.rs) automatically.
- This structure enables the monorepo to maintain dozens of isolated microservices—such as `entity_mentions`, `search_service`, and `email_service`—with clear boundaries and independent compilation units.

## Frequently Asked Questions

### What does the src directory contain in the macro-inc/macro repository?

The `src` directory contains the Rust source files for each crate in the workspace, including entry points ([`lib.rs`](https://github.com/macro-inc/macro/blob/main/lib.rs) or [`main.rs`](https://github.com/macro-inc/macro/blob/main/main.rs)) and sub-modules that implement business logic, database access, and HTTP handlers for services like `document-storage-service` and `search_service`.

### How does Cargo locate modules in the macro-inc/macro workspace?

Cargo uses the `src` directory as the root for module resolution. When a file declares `mod foo;`, the compiler searches for [`src/foo.rs`](https://github.com/macro-inc/macro/blob/main/src/foo.rs) or [`src/foo/mod.rs`](https://github.com/macro-inc/macro/blob/main/src/foo/mod.rs) relative to the crate root, as implemented in crates like `search_service` and `entity_mentions`.

### Why does every crate in macro-inc/macro have its own src folder?

Each crate functions as an independent compilation unit within the workspace. Having a dedicated `src` directory per crate allows Cargo to build services in isolation, enforce separation of concerns between microservices, and manage dependencies independently for components like `email_service` and `authentication_service`.

### Where are the binary entry points located in the macro-inc/macro services?

Binary entry points reside in [`src/main.rs`](https://github.com/macro-inc/macro/blob/main/src/main.rs) within individual crates. Library crates expose their functionality through [`src/lib.rs`](https://github.com/macro-inc/macro/blob/main/src/lib.rs), which binaries can import or which other workspace members can depend on to share code between services.