ERP-core/README.md

ERP System — Inventory & Supply Chain (Phase 1)

A modular ERP built in phases. Phase 1 delivers Inventory & Supply Chain: master data, procurement, goods receipt, and stock management with FIFO costing, multi-warehouse, single-tenant.

Monorepo: a .NET 10 REST API backend and a Next.js frontend, with all documentation under docs/.

Repository layout

erp-monorepo/
├── Backend/      # ASP.NET Core Web API (.NET 10, PostgreSQL) + PROGRESS.md
├── Frontend/     # Next.js (App Router, TypeScript) + PROGRESS.md
└── docs/         # all documentation — START AT docs/00-CORE.md

Start here

All work begins at docs/00-CORE.md — the hub. It defines structure, tech stack, backend setup, and routes you to the right doc.

Doc	Purpose
docs/00-CORE.md	Hub: structure, stack, backend init, routing
docs/01-DOC-GUIDE.md	Doc map, reading order, tracking conventions
docs/10-BACKEND-PHASE1.md	Backend spec: SRS + ER model + architecture
docs/11-BACKEND-PHASE1.md	Backend API reference (complete req/res)
docs/20-FRONTEND.md	Frontend user-flows + rules + validation posture
docs/40-DEPLOYMENT.md	CI/CD pipelines, test/release environments, server runbook
Backend/PROGRESS.md, Frontend/PROGRESS.md	Change checklists (git-shared)

Prerequisites

• .NET 10 SDK (dotnet --version → 10.0.x)
• PostgreSQL running on localhost
• dotnet-ef tool (dotnet tool install --global dotnet-ef)
• Node.js (for the frontend)

Run the backend

# create the database in your local Postgres first, e.g.:
#   createdb -U postgres ERPCore   (or: CREATE DATABASE "ERPCore"; in psql)
cd Backend/ERPCore
# local settings are git-ignored: copy the template, then fill in your Postgres login and the GL key
cp appsettings.Development.json.example appsettings.Development.json
dotnet ef database update
dotnet run

• Swagger UI: https://localhost:<port>/swagger
• Health: https://localhost:<port>/health → Healthy

Full setup (packages, folder scaffold, Program.cs wiring) is in docs/00-CORE.md §5.

Run the frontend

cd Frontend/erp-system
cp .env.local.example .env.local      # BACKEND_ORIGIN=http://localhost:5224 (the Next proxy target)
npm install
npm run dev

Configuration & secrets

• appsettings.json is committed and holds no secrets; environment-specific values are blank there.
• Local: appsettings.Development.json (git-ignored, from the .example). Deployed (production): set in the env: block of .gitea/workflows/ci-cd.yml; the deploy generates appsettings.Production.json from it on each run, with the DB password and GL API key coming from Gitea secrets — outside Development the API refuses to start when a required key is missing.
• Details and the full key list: docs/40-DEPLOYMENT.md §5. Credentials committed in the past must be rotated (docs/02-SECURITY.md AR-06).

Deployment

One workflow, .gitea/workflows/ci-cd.yml, does both jobs. Pull requests get checks (only the changed side is checked), and merging a PR into production deploys production (erp.hexdive.com) Fitness-style: publish on the server → stop → copy → start → verify, and only for the backend/frontend whose folder changed. A test environment is designed but on hold (deploy/on-hold/). See docs/40-DEPLOYMENT.md.

Tech stack

Backend: .NET 10, ASP.NET Core Web API, EF Core 10, PostgreSQL (Npgsql), JWT bearer auth, Serilog, Swashbuckle/Swagger, HealthChecks. Layering: Controller → Service → Repository → UnitOfWork, DTOs at the controller boundary, FIFO in a domain service. Frontend: Next.js (App Router) + TypeScript, plain React hooks, dependency-free validation (client for UX; server is authoritative).

Conventions

• Documentation: one source of truth per topic; edit in place; navigate from docs/00-CORE.md.
• Progress: update the relevant PROGRESS.md in the same commit as the code (docs/01-DOC-GUIDE.md §6).

Roadmap (future phases)

Sales & CRM · Manufacturing & Production · QC/QA · Accounting · HRM. Phase 1 reserves the integration seams (GL-ready journal entries, reservation status, goods-issue movement, inspection hold, user identity) so later phases integrate without a schema migration.