Project Structure¶

unicorn-trails/
├── UnicornTrails.API/           # Backend solution
├── UnicornTrails.Client/        # Frontend app
├── UnicornTrails.Docs/          # Documentation (you are here)
├── planning/                    # Planning documents
├── .github/                     # GitHub Actions workflows
└── README.md

UnicornTrails.API/
├── UnicornTrails.API/              # Host project
│   ├── Controllers/                # HTTP endpoints
│   ├── Middlewares/                # Request pipeline
│   └── Program.cs                  # App configuration
│
├── UnicornTrails.API.Application/  # Business logic
│   └── Features/                   # Vertical slices
│       └── {Feature}/
│           ├── Commands/           # Write operations
│           ├── Queries/            # Read operations
│           ├── Models/             # DTOs
│           └── Validators/         # Request validation
│
├── UnicornTrails.API.Domain/       # Core domain
│   ├── Entities/                   # Domain entities
│   ├── Enums/                      # Enumerations
│   ├── Abstractions/               # Interfaces
│   ├── Constants/                  # Domain constants
│   └── Exceptions/                 # Custom exceptions
│
├── UnicornTrails.API.Infrastructure/  # External concerns
│   ├── Persistence/                # EF Core, migrations
│   ├── Services/                   # Infrastructure services
│   └── Configuration/              # Config extensions
│
├── Integrations/                   # External services
│   ├── .../Email/                  # Resend integration
│   ├── .../GeoCode/                # Geocoding
│   └── .../Turnstile/              # CAPTCHA
│
└── Tests/
    ├── .../Tests.Unit/             # Unit tests
    └── .../Tests.Integration/      # Integration tests

UnicornTrails.Client/
├── src/
│   ├── app/                     # Entry + app shell (main.tsx, App.tsx, theme, pwa, env, sentry)
│   │
│   ├── features/                # Feature modules (account, admin, budget, hub, map, notes, settings)
│   │   └── {feature}/
│   │       ├── api/             # keys.ts, queries.ts, mutations.ts (TanStack Query)
│   │       ├── components/      # Feature components
│   │       ├── hooks/           # Feature hooks
│   │       ├── stores/          # Feature Zustand stores (if needed)
│   │       ├── constants.ts     # Feature constants
│   │       └── {Feature}Page.tsx
│   │
│   ├── components/              # Shared components
│   │   ├── ui/                  # Button, InfoTooltip, DonutChart, PaginatedList/Table, ...
│   │   ├── feedback/            # EmptyState, dialogs/, skeletons/, toast/
│   │   ├── forms/               # FormModal, *Field wrappers, selectors, RichText*
│   │   ├── images/              # ImageUpload, ImageCropper, FullscreenImageViewer, ...
│   │   ├── layout/              # PageShell, ErrorBoundary, HubButton, ModalStackHandler
│   │   └── routing/             # Route guards (ProtectedRoute, GuestRoute)
│   │
│   ├── api/                     # Shared API layer (generated SDK, http/, files/, queryClient,
│   │                            # pagination, cacheUtils, fetchInterceptor)
│   ├── stores/                  # Global Zustand stores
│   ├── hooks/                   # Shared hooks (browser/, files/, modals/, optimistic/ + root)
│   ├── utils/                   # Shared utilities (format/, files/ + root: jwt, storage, toast, ...)
│   ├── constants/               # App-wide constants
│   └── i18n/                    # Translations
│
├── tests/
│   ├── e2e/                     # Playwright tests
│   │   ├── features/            # Feature tests
│   │   └── shared/              # Test utilities
│   └── unit/                    # Vitest tests
│
└── public/                      # Static assets