Project Structure¶

Folder organization for the codebase.

Repository Root¶

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

Backend Structure¶

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

Frontend Structure¶

UnicornTrails.Client/
├── src/
│   ├── api/                     # API layer
│   │   └── {feature}/           # Feature-specific
│   │       ├── keys.ts          # Query keys
│   │       ├── queries.ts       # Read hooks
│   │       └── mutations.ts     # Write hooks
│   │
│   ├── components/              # Shared components
│   │   ├── common/              # Commonly used (Button, InfoTooltip)
│   │   ├── display/             # Visual display (AmountDisplay, TruncatedText)
│   │   ├── feedback/            # User feedback (EmptyState, ErrorBoundary)
│   │   ├── forms/               # Form components
│   │   │   ├── fields/          # Field wrappers (*Field)
│   │   │   ├── selectors/       # Selection UI (*Selector)
│   │   │   ├── security/        # Form security
│   │   │   └── accessibility/   # Accessibility
│   │   ├── tables/              # Tabular data
│   │   ├── images/              # Image handling
│   │   ├── dialogs/             # Modal dialogs
│   │   ├── layout/              # Page layout
│   │   ├── navigation/          # Navigation
│   │   ├── pwa/                 # PWA components
│   │   └── routing/             # Route guards
│   │
│   ├── pages/                   # Route components
│   ├── stores/                  # Zustand stores
│   ├── hooks/                   # Custom hooks
│   │   ├── app/                 # App lifecycle (events, language)
│   │   ├── budget/              # Budget-specific hooks
│   │   ├── data/                # Data management (pagination)
│   │   ├── images/              # Image handling hooks
│   │   ├── modals/              # Modal state hooks
│   │   └── ui/                  # UI utilities (timeout, countUp)
│   ├── constants/               # App constants
│   ├── i18n/                    # Translations
│   ├── config/                  # Configuration
│   └── utils/                   # Utility functions
│       ├── auth/                # storage, jwt helpers
│       ├── format/              # currency, date, number, string formatting
│       ├── form/                # form error handling
│       ├── image/               # image crop, file helpers
│       └── ui/                  # toast, icons, lazy loading
│
├── tests/
│   ├── e2e/                     # Playwright tests
│   │   ├── features/            # Feature tests
│   │   └── shared/              # Test utilities
│   └── unit/                    # Vitest tests
│
└── public/                      # Static assets

Key Files¶

Backend¶

File	Purpose
`Program.cs`	App startup, DI configuration
`appsettings.json`	Default configuration
`DataContext.cs`	EF Core DbContext

Frontend¶

File	Purpose
`App.tsx`	Root component, routing
`main.tsx`	Entry point
`theme.ts`	MUI theme configuration
`vite.config.ts`	Build configuration