Engineering onboarding

Welcome to the SmartSRED / SREDSimplify monorepo. This page is the first-week checklist for engineers: what to install, how to run the stack, where code lives, and how we ship.

Before you write code

1. GitHub access — Clone the repository and confirm you can open pull requests.
2. Secrets for local runs — Many flows expect Doppler (or equivalent) for env injection; see Tools quickstart and scripts referenced in Tooling reference.
3. Read the release model — Application production deploys from semantic version tags (vX.Y.Z), not from every merge to main. The canonical summary is in repository AGENTS.md at the root.

Repository map

Path	Stack	Role
frontend/	Next.js (App Router), TypeScript, Tailwind, shadcn/ui	Marketing, auth, workspace UI; talks to backend through the Next.js BFF under /api/bff/
backend/	Spring Boot 3.x, Java 17	REST API, auth, billing, SR&ED workflows
backend/python-service/	FastAPI	Document and AI-heavy workers invoked from Java
docs/	VitePress	This documentation site (npm run docs:dev from docs/)
.github/workflows/	GitHub Actions + gh-aw Markdown	CI, security scans, release automation

Deeper module notes live under Architecture hub.

Local prerequisites

• Node.js 20 (match CI; see docs-ci.yml and frontend tooling).
• Java 17 and Maven for the Spring Boot service.
• Python 3.11+ with uv for the python service (see backend/python-service README if present).
• Docker (optional but recommended for parity with production images).
• Doppler CLI when using start.sh and production-like envs.

Exact versions and commands drift; prefer the scripts in Tooling reference over copying old shell snippets.

Verified startup (high level)

1. From repo root, follow Tools quickstart for the path your team uses (start.sh vs manual npm / mvn).
2. Confirm the frontend dev server, backend API, and (if needed) python-service are reachable.
3. Log in with documented test credentials only on non-production environments.

Branch, review, and merge

• Default integration branch: main (should stay releasable).
• Pull requests need at least one approval (see Conventions).
• Use Conventional Commits (feat:, fix:, docs:) so release automation can infer the next tag.

Testing expectations (by layer)

Layer	Command (from repo docs)	When
Frontend	cd frontend && npm run lint && npm run typecheck && npm run test:unit	Any frontend/ change
Backend	cd backend && mvn test	Any backend/ change
Python	cd backend/python-service && uv run pytest	Any python-service/ change
Docs	cd docs && npm run docs:build	Any docs/ change

See AGENTS.md for the full validation matrix.

Documentation ownership

• Every docs page should carry owner and last_reviewed in frontmatter (see existing pages).
• Large IA or process changes should update Documentation site map and .vitepress/config.mjs together so navigation stays honest.

Where to go next

• Conventions — day-to-day engineering standards
• Documentation site map — full public surface area
• Architecture hub — system design
• Tooling reference — scripts and workflows