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

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 and 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 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: 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: 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 or 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:

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:

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. The start_worker function implements an infinite loop with timed polling, typical for email queue processing:

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: Implements the core API for document storage and retrieval, handling persistence logic and storage interactions.
• authentication_service/src/lib.rs: Contains user authentication flows, password verification, and JWT token management systems.
• 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: 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 serves as the library entry point exposing public APIs, while 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 or 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 or 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 or 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 within individual crates. Library crates expose their functionality through src/lib.rs, which binaries can import or which other workspace members can depend on to share code between services.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}