Project Structure and Key Files
This page covers the DST directory layout, key files to study, and the reference implementation you should model new features after.
For detailed explanations of the architecture layers, see the Frontend Architecture and Backend Architecture guides.
Directory Structure
DST-Dev/
├── backend/ # ASP.NET Core application
│ ├── src/
│ │ ├── DST.Domain/ # Entities (POCOs, no EF attributes)
│ │ ├── DST.Application/ # Services, Interfaces, DTOs
│ │ ├── DST.Infrastructure/ # DbContext, Repositories, EF Config
│ │ └── DST.API/ # Controllers, Program.cs
│ └── tests/
├── frontend/ # React 19 + Vite + Tailwind CSS 4
│ └── src/
│ ├── api/ # HTTP utility and API modules
│ ├── app/ # App shell (Layout, router, index.css)
│ ├── components/
│ │ ├── common/ # Shared UI primitives and patterns
│ │ └── screening/ # Feature-specific components
│ ├── contexts/ # React context providers
│ ├── data/ # Static configuration data
│ ├── demo/ # Demo data for "Example Dam"
│ ├── hooks/common/ # Shared utility hooks
│ ├── pages/ # Page components (one per route)
│ └── utils/ # Utility functions
├── db/ # Database snapshots
├── docs/ # Documentation
├── scripts/ # Start/stop scripts
├── CLAUDE.md # Architecture standards
├── docker-compose.yml # PostgreSQL container
├── start-dev.bat # Start everything
└── end-dev.bat # Stop everything
Reference Implementation: PFM-01
PFM-01 (Overtopping Erosion) is the fully-implemented module you should model new features after. It demonstrates the complete five-layer frontend architecture and four-layer backend Clean Architecture.
Frontend Layers
| Layer | File |
|---|---|
| Page component | frontend/src/pages/screening/response/failure-mode-evaluation/pfm-01/Pfm01Page.jsx |
| Controller hook | frontend/src/pages/.../pfm-01/hooks/usePfm01Controller.js |
| Data hook | frontend/src/pages/.../pfm-01/hooks/usePfm01Data.js |
Backend Layers
| Layer | File |
|---|---|
| Domain entity | backend/src/DST.Domain/Entities/Screening/Response/FmEvaluation/Pfm01/Pfm01.cs |
| EF configuration | backend/src/DST.Infrastructure/Configurations/.../Pfm01Configuration.cs |
| Repository | backend/src/DST.Infrastructure/Repositories/.../Pfm01Repository.cs |
| Controller | backend/src/DST.API/Controllers/.../Pfm01Controller.cs |
Shared Components
These are the most commonly used building blocks for new pages:
| Component | Location | Purpose |
|---|---|---|
Section | components/common/layout/Section.jsx | Section wrapper with blue accent bar, title, optional collapse |
PageContainer | components/common/layout/PageContainer.jsx | Page-level wrapper with background and padding |
FormFieldGroup | components/common/layout/FormFieldGroup.jsx | Responsive grid for form fields |
EditableGridTable | components/common/table/EditableGridTable.jsx | Full-featured editable table |
BaseChart | components/common/chart/BaseChart.jsx | Chart.js wrapper for all chart types |
useDebounce | hooks/common/useDebounce.js | Debounced auto-save hook |
Key Backend Files
These are the files you'll need to modify when adding a new feature:
| File | Purpose |
|---|---|
DST.Application/DTOs/Common/ApiResponse.cs | Standard API response envelope |
DST.Application/DTOs/Common/JsonDefaults.cs | JSON serialization settings for JSONB |
DST.Infrastructure/Data/DSTDbContext.cs | Database context (register your entity here) |
DST.Infrastructure/DependencyInjection.cs | Register your repository here |
DST.Application/DependencyInjection.cs | Register your service here |
DST.API/Program.cs | Application entry point |
For details on the standard messaging contract (ApiResponse<T>), dependency injection, and database configuration patterns, see the Backend Architecture guide.
Import Aliases
The frontend uses path aliases so you don't need relative paths like ../../../components/common/ui/Button:
import Button from '@components/common/ui/Button';
import Section from '@components/common/layout/Section';
import PageContainer from '@components/common/layout/PageContainer';
import { useDebounce } from '@hooks/common/useDebounce';
import { http } from '@api/http';
The full list of aliases is in frontend/vite.config.js under resolve.alias.
Database Schema
For details on the database table structure, naming conventions, and design patterns (including the three-table SRP pattern for PFM modules), see the DST Database Schema Reference.