Feature/fs content by Marpheus · Pull Request #109 · futuredapp/Engineering-Handbook

Marpheus · 2026-03-04T17:05:07Z

No description provided.

Copilot

Pull request overview

Expands the Full-stack team section of the Engineering Handbook by replacing “Work in progress” placeholders with substantial documentation, and adds MkDocs support for Mermaid code fences so architecture diagrams can be embedded in the docs.

Changes:

Added comprehensive Full-stack documentation across tech stack, security, deployment/operations, coding standards, and appendices.
Introduced an “AI-Assisted Development” guide and linked it in navigation/index pages.
Updated MkDocs markdown extension configuration to support Mermaid fenced blocks.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
mkdocs.yml	Adds Full-stack nav entry for AI tools and configures `pymdownx.superfences` custom fence for Mermaid blocks.
docs/teams/fullstack/tech_stack/40_integrations.md	Replaces placeholder with integration patterns and Mermaid diagrams.
docs/teams/fullstack/tech_stack/30_devops.md	Replaces placeholder with DevOps/infra overview, Docker, CI/CD, and Mermaid diagrams.
docs/teams/fullstack/tech_stack/20_database.md	Replaces placeholder with DB/ORM/migration guidance and Mermaid diagrams.
docs/teams/fullstack/tech_stack/10_backend.md	Replaces placeholder with backend architecture and API patterns (includes Mermaid diagrams).
docs/teams/fullstack/tech_stack/00_frontend.md	Replaces placeholder with frontend architecture, tooling, and Mermaid diagrams.
docs/teams/fullstack/security/10_privacy.md	Replaces placeholder with privacy/GDPR and implementation guidelines.
docs/teams/fullstack/security/00_auth.md	Replaces placeholder with auth/authz patterns (JWT/OAuth/Firebase/RBAC).
docs/teams/fullstack/index.md	Updates section headings/links and removes “🚧” markers in favor of concrete summaries.
docs/teams/fullstack/docs/10_api_docs.md	Replaces placeholder with REST/GraphQL documentation standards and examples.
docs/teams/fullstack/docs/00_code_docs.md	Replaces placeholder with documentation philosophy and templates.
docs/teams/fullstack/development/30_project_setup.md	Updates branch naming (`develop`) and modernizes docker compose commands; adds AI scaffolding note.
docs/teams/fullstack/development/10_pull_request_guidelines.md	Updates PR self-review and reviewer assignment guidance.
docs/teams/fullstack/dev_env/20_ai_tools.md	New guide for AI-assisted development and security rules.
docs/teams/fullstack/dev_env/10_secrets.md	Modernizes docker compose examples and improves secrets docs formatting.
docs/teams/fullstack/dev_env/00_local_setup.md	Updates setup steps (develop branch, docker compose commands) and adds local domain notes.
docs/teams/fullstack/deployment/20_monitoring.md	Replaces placeholder with monitoring/logging/healthcheck guidance.
docs/teams/fullstack/deployment/10_rollback.md	Replaces placeholder with rollback procedures and decision tree.
docs/teams/fullstack/deployment/00_deployment.md	Replaces placeholder with CI/CD workflow and environment promotion guidance.
docs/teams/fullstack/coding_standards/40_error_handling.md	Updates logging section to align on Pino/nestjs-pino (removes Winston example).
docs/teams/fullstack/coding_standards/30_testing.md	Replaces placeholder with testing philosophy, conventions, and tool overview.
docs/teams/fullstack/coding_standards/10_linting.md	Clarifies linting/formatting approach and adds note on evolving tooling.
docs/teams/fullstack/coding_standards/00_style_guides.md	Updates Vue guidance to `<script setup lang="ts">` + composables examples.
docs/teams/fullstack/appendices/30_templates.md	Replaces placeholder with PR/README/docker-compose templates.
docs/teams/fullstack/appendices/20_faq.md	Replaces placeholder with onboarding/dev/review/deploy FAQ.
docs/teams/fullstack/appendices/10_scripts.md	Replaces placeholder with commonly used scripts/commands (Docker/DB/Git helpers).
docs/teams/fullstack/appendices/00_glossary.md	Expands glossary with additional modern terms (CI, IaC, E2E, etc.).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/teams/fullstack/appendices/10_scripts.md

mkdocs.yml

docs/teams/fullstack/tech_stack/10_backend.md

docs/teams/fullstack/tech_stack/00_frontend.md

docs/teams/fullstack/appendices/10_scripts.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

chore: current state updates

honzarac

pěkný :)

honzarac · 2026-03-12T09:40:49Z

docs/teams/fullstack/appendices/30_templates.md

+      - cache
+
+  postgres:
+    image: postgres:16-alpine


postgre 16 v template? co takhle už 18 :)

honzarac · 2026-03-12T10:06:41Z

docs/teams/fullstack/docs/10_api_docs.md

+    findOne(@Param('id', ParseUUIDPipe) id: string): Promise<UserResponseDto> {
+        return this.usersService.findOne(id)
+    }
+}


no tady bych se o tom ještě pobavil. Já už jsem kolikrát říkal, že definování api dokumentace přes tyhle dekorátory se mi moc nelíbí, ale whatever, pokud se na tom shodnem, tak můžem jit tudy.

co mě na tomto přístupu vadí víc než bordelení kódu je, že do procesu definice api takhle nejsou zapojení mobile devs. Apičko definujeme my, to je jasné, ale vstupy od kluků jsou většinou fajn, protože tam vidí problémy zas ze svojí strany.

Tohle vypadá fajn na generování bez zaplevelení kódu: https://docs.nestjs.com/openapi/cli-plugin

honzarac · 2026-03-12T10:12:36Z

docs/teams/fullstack/docs/10_api_docs.md

+GraphQL Playground (or Apollo Sandbox) is available at the GraphQL endpoint in development. It provides:
+
+- Interactive query builder
+- Auto-complete based on the schema


právě no... s graphkem máš autocomplete, tak by mi dávalo smysl, kdybychom na začátek dávali spíše název modelu, než tu akci takže "userCreate" spíš než "createUser". Protože tím autocompletem si můžeš chytnout entitu se kterou pracuješ a potom vidíš dostupné akce spíš než další desítky create akcí

zkoušel jsem tu konvenci zavést na kruhu, ale trochu se nám to rozjelo. Není major problém, ale přišlo by mi fajn, můžem se pobavit.

honzarac · 2026-03-12T10:19:40Z

docs/teams/fullstack/security/00_auth.md

+- **Refresh tokens** should be stored securely and rotated on use
+- **Rate limit** authentication endpoints to prevent brute force attacks
+- **Never log** tokens, passwords, or authentication payloads
+- **Invalidate sessions** on password change


jaké sessions? když máme JWT, tak session neexistuje ne? většinou to máš buď JWT, nebo nějakou session a invalidace tokenu může probíhat se získáním nového access tokenu

taky by bylo fajn zmínit, že když jdeme cestou JWT, tak není dobrá practise si pokaždé vytahovat usera z databáze, že tím přicházíš právě o výhody JWT

honzarac · 2026-03-12T10:24:36Z

docs/teams/fullstack/tech_stack/10_backend.md

+    constructor(private readonly usersService: UsersService) {}
+
+    @Get()
+    findAll(@Query() query: PaginationDto): Promise<PaginatedResponse<User>> {


píšeš o tom, že bysme neměli vracet entity jako DTOčka do api (souhlas), ale tady to teda vypadá jako root entita, kterou používáš pro response. Možná by ten název mohl reflektrovat, že jde o nějaké custom DTO.

je to i niž u graphka :)

honzarac · 2026-03-12T10:27:38Z

docs/teams/fullstack/tech_stack/10_backend.md

+
+| Use REST when... | Use GraphQL when... |
+|---|---|
+| Simple CRUD operations | Complex nested data relationships |


i s tou data complexity si nejsem jistý. Kruh má komplexní data a nejsem si jistý, že nám to v něčem pomáhá. Zvlášť když appka i front používá to graphko často jako rest. A nemáme plán na to, jak verzovat modely v graphku, leda prostě suffixovat v2 a tak no.

honzarac · 2026-03-12T10:28:57Z

docs/teams/fullstack/tech_stack/10_backend.md

+
+## Validation
+
+All incoming data is validated using DTOs with `class-validator`:


co nějaká poznámka ke class-validatoru, jak blbě handluje nested data, že je potřeba si na to dát bacha?

honzarac · 2026-03-12T10:34:51Z

docs/teams/fullstack/tech_stack/30_devops.md

+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./
+


node 20? :)

jinak ten multistage build setup by měl být složitější. Protože nejdřív potřebuješ instalovat i dev dependencies abys byl schopný to zbuildit a pro produkční container stáhnout packages bez dev dependencies

honzarac · 2026-03-12T10:36:23Z

docs/teams/fullstack/tech_stack/30_devops.md

+### Where We Are
+
+- Infrastructure for most projects is provisioned manually (cloud consoles, CLI)
+- A handful of projects use **Terraform** with basic GCP or Digital Ocean resource definitions


fakt jo? to někde máme?

vím jen o prastarém nesnězenu a národním muzeu

harleyka · 2026-03-16T12:30:25Z

docs/teams/fullstack/appendices/00_glossary.md

 **SPA (Single Page Application)**  
 A web application that loads a single HTML page and dynamically updates content as the user interacts with the app.

+**SSR (Server-Side Rendering)**  


Chybí mi tu zmínka o SSG, když už ho používáme 🙂

harleyka · 2026-03-16T12:52:37Z

docs/teams/fullstack/appendices/10_scripts.md

+docker compose exec postgres psql -U myuser -c "CREATE DATABASE mydb;"
+
+echo "Running migrations..."
+docker compose exec api npm run migrate


npm nepoužíváme, ale je to všude
možná dobrý nápad zvalidovat i to, jestli chceme zůstat u yarn

harleyka · 2026-03-16T12:55:13Z

docs/teams/fullstack/appendices/20_faq.md

+
+We don't mandate a specific IDE. Most team members use:
+
+- **WebStorm** (JetBrains) — Full-featured, excellent TypeScript/Vue support


Přidala bych, že je to self-paying, aby nebylo mrzení

a je? já si to nechávám proplácet 🤔

aha, to je vtipné, mi bylo řečeno, že si to mám zaplatit sama 🙂

harleyka · 2026-03-16T12:58:52Z

docs/teams/fullstack/appendices/20_faq.md

+
+See the [Backend](../tech_stack/10_backend.md) page for a comparison table. In short:
+
+- **REST** for simple CRUD, public APIs, file operations, webhooks


and scheduled jobs

harleyka · 2026-03-16T13:06:16Z

docs/teams/fullstack/appendices/20_faq.md

+
+### What should I focus on during code review?
+
+1. **Correctness** — Does the code do what it's supposed to?


Chybí mi tu ještě readability (naming, apod.) a efficiency

harleyka · 2026-03-18T12:21:51Z

docs/teams/fullstack/tech_stack/00_frontend.md

+
+**Key capabilities:**
+
+- **Server-side rendering** — Fast initial page loads and SEO for public-facing apps


To zrovna nevyužíváme 🤣

harleyka · 2026-03-18T12:24:19Z

docs/teams/fullstack/tech_stack/00_frontend.md

+├── plugins/            # Nuxt plugins (Sentry, etc.)
+├── server/             # Server routes and middleware
+│   └── api/
+├── types/              # TypeScript type definitions


Chybí mi tu ještě utils na auto-imported helper funkce

harleyka · 2026-03-18T12:26:27Z

docs/teams/fullstack/tech_stack/00_frontend.md

+
+- **Auto-imports**: Nuxt auto-imports Vue APIs and composables — no need for manual imports in most cases
+- **CSS**: Use scoped styles in components. For shared styles, use a CSS framework or utility classes as appropriate for the project
+- **API calls**: Use Nuxt's `$fetch` or `useFetch` composable for data fetching with built-in SSR support


Zrovna fetche nepoužíváme, když si generujeme API EPs ze Swaggeru :/ + nemáme to SSR a nevím, jestli někdy mít budem - budeme oddělovat BE od FE, abychom SSR mohli použít? Budeme ho potřebovat?

harleyka · 2026-03-18T12:26:43Z

docs/teams/fullstack/tech_stack/00_frontend.md

+### Key Conventions
+
+- **Auto-imports**: Nuxt auto-imports Vue APIs and composables — no need for manual imports in most cases
+- **CSS**: Use scoped styles in components. For shared styles, use a CSS framework or utility classes as appropriate for the project


Doplnila bych ještě někde, že používáme Tailwind pro css

harleyka · 2026-03-18T12:27:07Z

docs/teams/fullstack/tech_stack/00_frontend.md

+├── types/              # TypeScript type definitions
+└── nuxt.config.ts      # Nuxt configuration
+```
+


Ještě bych doplnila použití i18n jako standard, i když se explicitně nepoužívá vícero jazyků.

harleyka · 2026-03-19T10:57:16Z

@Marpheus Masakrálně mega moc textu 😄 Ale dobře udělané, napadlo mě tam pár drobností.

pirky · 2026-03-20T09:08:44Z

docs/teams/fullstack/tech_stack/10_backend.md

+|---|---|
+| **NestJS** | Medium-to-large projects, complex business logic, multiple modules, long-term maintenance |
+| **Express / Fastify** | Small APIs, microservices, tight budgets, simple CRUD |
+| **Hono** | Edge-first APIs, serverless functions, minimal footprint |


Mame niekde pouzite Hono, alebo preco je tu uvedene ako priklad?

pirky · 2026-03-20T09:31:17Z

docs/teams/fullstack/coding_standards/40_error_handling.md

 });
 ```

 ### 2. REST API Error Handling (Non-GraphQL Apps)


Mne by sa pacilo, keby pouzivame error handling ako zaviedol na kruhu Adam, ked sme robili jablotron api. V principe sa jedna iba o cast error handlingu ako vyhadzovat chyby, kedy si predpripravis triedu so staticmi. Priklad triedy:

export class CommonErrors { static InvalidInputData() { return new ApplicationError( 'Request body does not match any of the expected types for this operation.', ErrorCodeEnum.BAD_USER_INPUT, HttpStatus.BAD_REQUEST, ) } }

nasledne uz iba hadzes dany error jednoducho takto:

throw CommonErrors.InvalidInputData()

Co mi pride ako prijemny vylepsovak obzvlast v pripadoch, ked sa rovnaky error pouziva na viacerych miestach. Tym zabezpecime aj ak chceme dany error pozmenit (textaci, alebo hadze nespravny errorCode), urobime tak na jednom mieste a nemusime po celej aplikacii hladat kde sa tento error hadze.

Marpheus added 17 commits March 4, 2026 15:00

chore: added glossary items

b5f0424

chore: updated styleguide FE part to composition API

ebb15ff

chore: updated linting section

be4f3fa

chore: updated local setup

e4725eb

chore: updated secrets section

fbc89b6

chore: added AI tools section

e8b605a

chore: updated template and pr guidelines

52f264d

chore: added ai section to the menu

188a316

chore: added useful scripts section

1556b29

chore: added faq section

f3570f9

chore: added templates section

ea76b21

chore: added testing section

c25672e

chore: added docs section

5ffcc15

chore: updated menu

67f60bb

chore: added security and privacy

da8d2df

chore: added deployment and operations

82a4aa2

chore: updated tech section

0ec605d

Copilot AI review requested due to automatic review settings March 4, 2026 17:05

Copilot started reviewing on behalf of Marpheus March 4, 2026 17:05 View session

Copilot AI reviewed Mar 4, 2026

View reviewed changes

Marpheus and others added 4 commits March 5, 2026 16:55

Update docs/teams/fullstack/appendices/10_scripts.md

3218be0

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/teams/fullstack/appendices/10_scripts.md

edf533d

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

chore: current state updates

0c529cb

Merge pull request #110 from futuredapp/feature/fs-content-update

6bfa30f

chore: current state updates

Marpheus requested review from harleyka, honzarac, pirky and sabgul March 10, 2026 14:49

honzarac reviewed Mar 12, 2026

View reviewed changes

harleyka reviewed Mar 19, 2026

View reviewed changes

pirky reviewed Mar 20, 2026

View reviewed changes

Marpheus requested a review from adacek March 23, 2026 13:04

chore: replace mermaid diagrams with png

ac82f45

sabgul force-pushed the feature/fs-content branch from 1d3d14f to ac82f45 Compare March 23, 2026 13:08

chore: fix large images

bc8d23a


		## Validation

		All incoming data is validated using DTOs with `class-validator`:


		We don't mandate a specific IDE. Most team members use:

		- WebStorm (JetBrains) — Full-featured, excellent TypeScript/Vue support


		See the [Backend](../tech_stack/10_backend.md) page for a comparison table. In short:

		- REST for simple CRUD, public APIs, file operations, webhooks


		### What should I focus on during code review?

		1. Correctness — Does the code do what it's supposed to?


		Key capabilities:

		- Server-side rendering — Fast initial page loads and SEO for public-facing apps

Conversation

Marpheus commented Mar 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

honzarac left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

harleyka commented Mar 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants