mirror of
https://github.com/Sea-Haven-Industries/shoc-backend.git
synced 2026-09-30 11:53:12 +00:00
Adam Moussa
b7b22a8893
The org PR template pre-filled Summary / Validation / Tests / Notes here while REVIEW_AND_PR_FRAMEWORK.md section 8 prescribes Summary / Changes and value / Ticket. A repo template now overrides the org one, and the framework notes the divergence from the org pr-policy workflow, which is not wired in. README.md orients a reader: environments, architecture in one line, project map, local commands, the governance gate, deployment, and a documentation map. Cleanup: TODO.md is removed because Jira owns work status and its items are stale or done. BACKEND_ARCHITECTURE.md is removed as superseded; the two references now point at git history. .env.example loses its BOM and mojibake dashes. .gitattributes keeps its one active rule.
115 lines
5.7 KiB
Markdown
115 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 `Build and test`,
|
|
`architecture` and `review / dependency-review` checks. 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.
|