diff --git a/README.md b/README.md index 304ea66..9c57c7b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,207 @@ # react-node-template This repository can be used as a template for future react-nodejs apps with Postgres DB. +# react-node-template +This repository can be used as a template for future React + Node.js apps with a Postgres DB. + +--- + +{{PROJECT_NAME}} +This repo is the source for the CHEFS code challenge and describes all aspects of the process, including agile team definitions, team agreements, design, deployment, and operations. + +--- + +## License +[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) + +--- + +## Team Agreements +#### Definition of Done (replace with relevant info) +- **All code:** Reviewed, merged to default branch; build succeeds on default; linter and static analysis checks pass (e.g., ESLint/Sonar). +- **API:** Unit tests defined (e.g., Jest) and passing. +- **UI:** End-to-end/UI tests defined (e.g., Cypress/RTL) and passing. +- **Sprint:** Any agreed smoke/automation tests pass; docs and change notes updated. +> {{LINK_TO_TEAM_WORKING_AGREEMENTS_OR_MEETING_CADENCE}} + +--- + +## Design +#### System Design - High Level (replace with relevant info) +- **User Interface:** A single {{FRONTEND_TECH}} web app; specific features/visibility may vary by role (RBAC). +- **APIs:** One or more REST (or GraphQL) services handling browser and system calls, secured per the authorization model. +- **Data:** {{PRIMARY_DB}} as the system of record; consider HA/replication/backup for production. +- **Web/Edge:** {{WEBSERVER_OR_PROXY}} as web server/reverse proxy (e.g., port 80/443). +- **Observability:** Logging, metrics, and tracing appropriate to {{HOSTING_ENVIRONMENT}}. +> Add/replace with relevant diagram: `![System diagram](./docs/system-diagram.png)` + +#### Reason for Choice of Stack (replace with relevant info) +This architecture was selected because: +- Familiar to the delivery team and common in {{YOUR_ORG_OR_JURISDICTION}}. +- Strong fit for containerization and cloud deployment (e.g., Docker, {{ORCHESTRATOR}}). +- Broad open-source ecosystem and community support. +- Scales horizontally and enables rapid iteration. + +--- + +## Data Model (replace with relevant info) +> Briefly describe core entities and relationships. Link an ERD if available. +- **Key entities:** {{ENTITY_LIST}} +- **Reference data / lookups:** {{LOOKUP_TABLES_OR_CONSTANTS}} +- **Bootstrap/seed data (optional):** {{HOW_BOOTSTRAP_DATA_IS_APPLIED}} +- **Example mapping table (replace as needed):** + + | Category | Level/Type | Required Attributes/Skills | + |-------------------|------------|----------------------------| + | {{CATEGORY_A}} | {{LEVEL}} | {{ATTRIBUTES}} | + | {{CATEGORY_B}} | {{LEVEL}} | {{ATTRIBUTES}} | + +> ERD (optional): `![ERD](./docs/data-model.png)` + +--- + +## Error Handling (replace with relevant info) +- **UI validation:** Clear inline messages, accessible patterns, constraints (format, length, required fields). +- **API validation:** Schema validation, consistent error envelope (code/message/details), idempotency where needed. +- **Duplicates & conflicts:** Detect and surface conflicts (e.g., existing record with same key) with actionable guidance. +- **Data hygiene:** Normalize inputs (e.g., phone format) to keep the database clean. + +--- + +## API Specifications (replace with relevant info) +- **Source of truth (OpenAPI):** `./backend/swagger-docs` or `./api/openapi` +- **Rendered docs (optional):** {{SWAGGER_UI_OR_REDOC_URL}} +- **Change process:** {{HOW_API_CHANGES_ARE_REVIEWED_VERSIONED_AND_COMMUNICATED}} + +--- + +## Pipeline +> Automations run on pull requests and merges to ensure quality and accelerate delivery. +- **Triggers:** On PR, on merge to default branch, on tags/releases. +- **Primary stages:** Lint → Unit tests → Build → (Optional) E2E → Package/Deploy. +- **Environments:** {{DEV}} → {{TEST/STAGING}} → {{PROD}}, with promotion rules. + +--- + +## Service Design (replace with relevant info) +> Activities and artifacts to ensure the service fits real user needs.* +- **Timeline / Roadmap:** {{ROADMAP_LINK_OR_DOC}} +- **Stakeholder mapping:** {{STAKEHOLDER_MAP_LINK}} +- **Collaborative sessions:** Discovery workshops with users/SMEs/developers. +- **Personas & Empathy maps:** {{PERSONAS_LINK}} (e.g., primary persona and empathy map) +- **Service blueprint:** {{BLUEPRINT_LINK}} (frontstage/backstage touchpoints) + +--- + +## UX Design (replace with relevant info) +> Evidence-based design to make the service usable and consistent.* +- **Journey mapping:** {{JOURNEY_MAP_LINK}} +- **Wireframes / Prototypes:** {{FIGMA_OR_WIREFRAME_LINK}} +- **FAQ / Help content:** {{FAQ_LINK}} + +**Anticipated design findings (replace with relevant info):** +- Provide contextual help/FAQ where users make choices. +- Allow users to update submissions post-creation (with audit trail). +- Support “other”/free-text entries where controlled lists may be incomplete. +- Capture location or other attributes needed for downstream matching. + +--- + +## Deployment Using Gitpod (Optional) +- **Why Gitpod:** Fast, preconfigured cloud dev environment; low setup time. +- **Start here:** {{GITPOD_LINK_OR_INSTRUCTIONS}} +- **Expected behavior:** Containers/services build and start automatically; preview ports shown in the IDE. +> Screenshot (optional): `![Gitpod](./docs/gitpod.png)` + +--- + +## Installation Instructions +#### Prerequisites +- **Runtime/tooling:** {{NODE_VERSION}}, {{PACKAGE_MANAGER}}, {{DATABASE_VERSION}} +- **Container (optional):** Docker & Docker Compose +- **Git CLI:** {{LINK_IF_NEEDED}} + +#### Local Deployment (replace the example flow below with details specific and relevant to code challenge) +```bash +# 1) Clone +git clone {{REPO_URL}} +cd {{LOCAL_FOLDER}} + +# 2) Start via script (if provided) +./start.sh + +# 3) Or Docker Compose +docker compose up -d + +# 4) Or run apps separately +# backend +cd api && cp .env.example .env && {{PACKAGE_MANAGER}} install && {{PACKAGE_MANAGER}} run dev +# frontend +cd ../web && cp .env.example .env && {{PACKAGE_MANAGER}} install && {{PACKAGE_MANAGER}} run dev +``` + +## Successful startup (replace with relevant info): +```bash +Creating network "project_net" with driver "bridge" +Creating db ... done +Creating api ... done +Creating web ... done + +``` +--- + +## Backlog & Sample User Story +#### Likely backlog additions (replace with relevant info) +- {{AUTHENTICATION_OR_SSO}} +- {{ROLE_BASED_ACCESS_CONTROL}} +- {{LOCATION_OR_ADDITIONAL_FIELDS}} +- {{ADMIN_MANAGEMENT_OF_LOOKUPS}} +- {{USER_SELF_SERVICE_EDITS}} +- {{AVAILABILITY_OR_SCHEDULING}} + +## Jira-ready user story (template) +- **Title:** {{BRIEF_TITLE}} +- As a {{USER_ROLE}}, I want {{CAPABILITY}}, so that {{BUSINESS_VALUE}}. +- **Acceptance criteria:** + - {{GIVEN_WHEN_THEN_1}} + - {{GIVEN_WHEN_THEN_2}} + - {{VALIDATION_OR_ERROR_CASES}} +- **Notes/Attachments:** {{LINKS_TO_DESIGN/FAQ}} + +--- + +## Assumptions & Privacy (replace with relevant info) +- **Assumptions:** {{KEY_ASSUMPTIONS}} (e.g., user knowledge, device, environment) +- **Privacy:** Purpose, consent, retention; sensitive fields handled appropriately; public views exclude private data. +- **Security:** {{AUTHN/AUTHZ_MODEL}}, least privilege; secrets not committed; audit/logging where appropriate. + +--- + +## CI/CD Pipeline (Detail) +#### Backend CI (example - replace with relevant info) +- Checkout code; install dependencies. +- Run route/integration tests (e.g., Jest + Supertest). +- Run static analysis (e.g., ESLint/Sonar). +- Build/package artifact or container image. + +#### Frontend CI (example - replace with relevant info) +- Checkout; install dependencies. +- Run unit tests (e.g., React Testing Library/Vitest). +- Lint/format checks. +- (Optional) Cypress smoke tests against a preview URL. +> Re-run specific workflow runs to validate fixes when needed. + +--- + +## Operations +- **Monitoring & logging:** {{WHERE_TO_FIND_LOGS/METRICS/DASHBOARDS}} +- **Support:** {{CONTACT_OR_SERVICE_DESK}}, SLAs, escalation path. +- **Known limitations:** {{LIST_OR_LINK}} +- **Post-incident review:** {{HOW_AND_WHERE_DOCUMENTED}} + +--- + +## Contacts +- **Sponsor / Owner:** {{NAME, ROLE}} +- **Product / Delivery:** {{NAME, ROLE}} +- **Engineering / Design:** {{NAME, ROLE}} +- **Support:** {{CHANNEL_OR_EMAIL}}