---
trigger: always_on
---

> **This file is the SINGLE SOURCE OF TRUTH for project organization.**
> All other rules and workflows that reference paths should defer to this file.
> To adapt the setup for a different project type, edit this file only.

## Project Structure

**Project Structure Philosophy:**

- **Organize by FEATURE, not by technical layer**
- Each feature is a vertical slice
- Enables modular growth, clear boundaries, and independent deployability

**Universal Rule: Context → Feature → Layer**

**1. Level 1: Repository Scope:** Root contains `apps/` grouping distinct applications (e.g., `apps/backend`, `apps/frontend`, `apps/mobile`).

**2. Level 2: Feature Organization**
   - **Rule:** Divide application into vertical business slices (e.g., `user/`, `order/`, `payment/`).
   - **Anti-Pattern:** Do NOT organize by technical layer (e.g., `controllers/`, `models/`, `services/`) at the top level.

### Language-Specific Layouts

Each layout follows the universal philosophy above. Load the relevant layout when working with a specific language or framework:

| Layout             | File                                 | When to Use                          |
| ------------------ | ------------------------------------ | ------------------------------------ |
| Go Backend         | @project-structure-go-backend.md     | Go services, APIs, CLI tools         |
| Vue/React Frontend | @project-structure-vue-frontend.md   | Web frontends (Vue, React, Svelte)   |
| Flutter/Mobile     | @project-structure-flutter-mobile.md | Mobile apps (Flutter, React Native)  |
| Rust/Cargo         | @project-structure-rust-cargo.md     | Rust binaries, libraries, workspaces |

> This Feature/Domain/UI/API structure is framework-agnostic. It applies equally to any language or framework. The layout files provide language-specific conventions (file naming, module systems, test locations) while preserving the vertical slice architecture.

### Adapting for Different Project Types

| Project Type            | What to Change                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
| **Monorepo** (default)  | Use as-is — `apps/backend/`, `apps/frontend/`, `apps/mobile/`                                     |
| **Single backend**      | Flatten to root: `cmd/`, `internal/` (Go) or `src/` (Rust) at project root                        |
| **Single frontend**     | Flatten to root: `src/` at project root (no `apps/` wrapper)                                      |
| **Single mobile**       | Flatten to root: `lib/` at project root (no `apps/` wrapper)                                      |
| **Single Rust binary**  | Flatten to root: `src/`, `tests/`, `benches/` at project root with `Cargo.toml`                   |
| **Rust library**        | Flatten to root: `src/`, `examples/`, `tests/` at project root with `Cargo.toml` (lib target)     |
| **Rust workspace**      | `crates/` at root with workspace `Cargo.toml` — each crate follows single-crate layout internally |
| **Microservices**       | One directory per service under `apps/` (each with own `go.mod`/`Cargo.toml`/`Dockerfile`)        |
| **Full-stack + mobile** | Use all relevant layout files under `apps/`                                                       |

**Single-app projects** don't need the `apps/` directory — put the language-specific root directories directly at the project root. The internal structure (features, platform, etc.) stays the same.

**Multiple entry points (CLI, workers, etc.):**

Go:
```
cmd/
  api/main.go         # HTTP server entry point
  cli/main.go         # CLI tool entry point
  worker/main.go      # Background worker entry point
```

Rust:
```
src/
  bin/
    api.rs            # HTTP server entry point
    cli.rs            # CLI tool entry point
    worker.rs         # Background worker entry point
  lib.rs              # Shared library code
```

**Microservices notes:**
- Each service is its own directory under `apps/` with its own `go.mod`/`Cargo.toml` and `Dockerfile`
- Each service follows the same layout internally (see language-specific files)
- Add `shared/` at root for cross-service contracts (protobuf, shared types) — keep this minimal
- Services communicate via API calls or message queues, never direct imports

### Related Principles
- Code Organization Principles @code-organization-principles.md
- Architectural Patterns — Testability-First Design @architectural-pattern.md