mirror of
https://github.com/Sea-Haven-Industries/shoc-backend.git
synced 2026-09-30 13:03:12 +00:00
114 lines
5.7 KiB
Markdown
114 lines
5.7 KiB
Markdown
# SHOC Backend (`shoc-backend`)
|
|
|
|
[](https://github.com/Sea-Haven-Industries/shoc-backend/actions/workflows/ci.yml)
|
|
[](https://github.com/Sea-Haven-Industries/shoc-backend/actions/workflows/deploy.yaml)
|
|
|
|
|
|
|
|
|
|
ASP.NET Core 8 API for Sea Haven facility management (SHOC): work orders, the
|
|
work-order board, dispatches and the vendor portal, uplift approvals,
|
|
notifications, and the dashboard. It is the backend for
|
|
[`shoc-frontend-new`](https://github.com/Sea-Haven-Industries/shoc-frontend-new),
|
|
which calls it directly over HTTPS.
|
|
|
|
| Environment | API | Elastic Beanstalk environment | Deployed by |
|
|
|---|---|---|---|
|
|
| dev | `https://api.dev.seahaven.com` | `shoc-backend-dev` | every push to `main` |
|
|
| staging | `https://api.staging.seahaven.com` | `shoc-backend-staging` | a `vX.Y.Z-staging` tag cut with `release.yaml` |
|
|
|
|
Both run in `us-east-1` on the .NET 8 Amazon Linux 2023 platform. Terraform in
|
|
`terraform/live/` owns the environments; GitHub Actions owns the application
|
|
versions. There is no production environment yet.
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
Controller -> I{Feature}Service -> I{Feature}DataService -> ApplicationDbContext
|
|
```
|
|
|
|
Controllers depend on feature service interfaces only. Business services depend
|
|
on feature data-service interfaces, never on `DbContext`. Data services own
|
|
Entity Framework Core and are the atomic commit boundary. Tenant scope is
|
|
derived on the server from claims, and authorization is enforced at service
|
|
entry. The rules and their reasons are in
|
|
[`ARCHITECTURE_AND_CODE_QUALITY.md`](ARCHITECTURE_AND_CODE_QUALITY.md).
|
|
|
|
| Project | Role |
|
|
|---|---|
|
|
| `Api.SeaHavenIndustries` | The deployed API: controllers, hosted services, infrastructure adapters, `Program.cs` |
|
|
| `SeaHaven.Services` | Business services, DTOs, validation, helpers |
|
|
| `SeaHaven.DataServices` | Feature data services over EF Core |
|
|
| `Data.SeaHavenIndustries` | Entities, `ApplicationDbContext`, Identity, migrations |
|
|
| `SeaHavenIndustries` | Legacy Blazor Server app sharing the data layer; not part of the API deployment |
|
|
| `Api.SeaHavenIndustries.Tests`, `SeaHaven.Services.Tests`, `SeaHavenIndustries.Tests` | xunit test projects |
|
|
|
|
## Local development
|
|
|
|
Requires the .NET 8 SDK and a reachable SQL Server. Configuration comes from
|
|
`appsettings*.json` placeholders, then user secrets, then environment
|
|
variables. `.env.example` lists every key, including the connection string, JWT
|
|
secret, SendGrid key and Sentry DSN. Do not commit real values.
|
|
|
|
```bash
|
|
dotnet restore SeaHavenIndustries.sln
|
|
dotnet build SeaHavenIndustries.sln --configuration Release
|
|
dotnet test SeaHavenIndustries.sln --configuration Release
|
|
dotnet run --project Api.SeaHavenIndustries
|
|
```
|
|
|
|
The full repository gate that CI runs, including architecture discovery, the
|
|
changed-file maintainability check, Terraform checks and app/Terraform
|
|
isolation:
|
|
|
|
```bash
|
|
BASE_REF=origin/main bash scripts/governance-check.sh
|
|
```
|
|
|
|
Migrations live in `Data.SeaHavenIndustries/Migrations` and are applied at
|
|
deploy time from a bundle the packaging script builds with `dotnet-ef`. Adding
|
|
one follows the G6 rules in [`QUALITY_GATES.md`](QUALITY_GATES.md).
|
|
|
|
## Contributing
|
|
|
|
- Branch from `main` with a `feature/`, `fix/`, `chore/`, `docs/` or
|
|
`refactor/` prefix and a kebab-case description.
|
|
- Commit subjects follow Conventional Commits. PR titles end with the Jira
|
|
key for product work.
|
|
- The PR body uses the three-section layout the template pre-fills: Summary,
|
|
Changes and value, Ticket. The reasoning is in
|
|
[`REVIEW_AND_PR_FRAMEWORK.md`](REVIEW_AND_PR_FRAMEWORK.md).
|
|
- `main` requires a code-owner review and the `ci-complete` check. PRs merge
|
|
through the merge queue, so a branch does not need to be updated with `main`
|
|
before it merges.
|
|
- Application code and `terraform/` do not change in the same PR (G13).
|
|
|
|
## Deployment
|
|
|
|
`deploy.yaml` packages the API with `scripts/package-elastic-beanstalk.sh`,
|
|
uploads the bundle to the Elastic Beanstalk bucket, updates the environment,
|
|
verifies the exact version is active, and smoke-tests it. The bundle carries a
|
|
self-contained EF Core migrations bundle that Elastic Beanstalk runs on the
|
|
leader instance before the new version starts
|
|
(`.ebextensions/01_migrations.config`). A push to `main` targets dev.
|
|
`release.yaml` cuts a SemVer tag from `main` and calls the same workflow for
|
|
staging. Both are described in the workflow headers and in
|
|
[`terraform/live/README.md`](terraform/live/README.md).
|
|
|
|
Renovate opens dependency PRs on the schedule in `.github/renovate.json`;
|
|
majors wait for approval on the Dependency Dashboard issue.
|
|
|
|
## Documentation
|
|
|
|
- [`AGENTS.md`](AGENTS.md): repo-specific rules for coding agents and the order
|
|
of precedence between the governance documents.
|
|
- [`ARCHITECTURE_AND_CODE_QUALITY.md`](ARCHITECTURE_AND_CODE_QUALITY.md): what
|
|
the architecture rules mean.
|
|
- [`QUALITY_GATES.md`](QUALITY_GATES.md): every gate, the command that runs it
|
|
locally, and where CI runs it.
|
|
- [`REVIEW_AND_PR_FRAMEWORK.md`](REVIEW_AND_PR_FRAMEWORK.md): review order,
|
|
evidence, and the PR description contract.
|
|
- [`docs/adr/`](docs/adr/): architecture decision records.
|
|
- [`docs/work-orders/`](docs/work-orders/): work-order board phase notes.
|
|
- [`postman/`](postman/): generated Postman collection and dev environment.
|
|
- [`terraform/README.md`](terraform/README.md): infrastructure runbook.
|