docs: architecture guide by jescalada · Pull Request #1391 · finos/git-proxy

jescalada · 2026-02-07T04:43:50Z

Closes #1325. Previous PR (#1335) got stuck because of a GitHub bug where comments on orphaned commits cannot be closed.

Previous PR description:

The architecture diagram can be edited from this file on diagrams.net
GitProxy_Architecture.drawio

To-do

Add section for authentication methods

Add section for databases

Add plugin guide

Add deployment guide - to be added later by @tabathad

Fix all the to-dos

…nos/git-proxy into 1325-architecture-guide-draft

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

…chain execution

…ove todos

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Co-authored-by: Thomas Cooper <57812123+coopernetes@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

…dit instructions

jescalada · 2026-02-11T05:33:14Z

@kriswest Ready to go!

kriswest

Should these docs move into /website/docs to keep it all in one place?

Also thinking about @andypols comments about separating docs in the website for end users and those configuring/deploying git proxy. The docs in this /docs folder are all useful to those deploying or upgrading, so perhaps we should take this oppurtunity to unite them and do that division?

jescalada · 2026-02-12T05:57:25Z

@kriswest I'm happy to do any additional refactoring in a separate PR. There are a few doc improvements I'd like to make such as better user distinction (end users, administrators, and contributors) and improved categorization.

These might be a bit extensive so I'd rather keep things tidy in smaller PRs!

coopernetes

LGTM. Let's get this merged so it's available for reference as part of 2.0.

kriswest

LGTM, although I'd like to see these docs integrated into /website in a subsequent PR (so we're not creating multiple docs locations)

jescalada · 2026-02-14T05:31:28Z

@kriswest Made issues for the remaining tasks: #1407, #1408 - will go ahead and merge this one!

jescalada and others added 30 commits December 27, 2025 16:03

docs: add basic overview of app architecture

66361d4

docs: extend app architecture overview

e514aeb

docs: add architecture diagram

4e853c2

docs: add basic flows and policy definition

b9a69d4

docs: add descriptions for all push/pull actions

b45d091

Merge branch 'main' into 1325-architecture-guide-draft

dd1796f

docs: add authentication section

95e4eca

docs: add entries for config parameters and customization

e3ea864

Merge branch 'main' into 1325-architecture-guide-draft

6dc9345

docs: add remaining config entries

57ebd03

docs: improve wording, fix typos, add missing links

3e2ca56

Merge branch '1325-architecture-guide-draft' of https://github.com/fi…

cb96240

…nos/git-proxy into 1325-architecture-guide-draft

docs: add screenshots and missing links, remove todos

ce66b6e

Update docs/Architecture.md

e2ad052

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

5ee2aef

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

d3e6650

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

cd16b78

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

754f5ec

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

3975018

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

c852875

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

docs: document missing audit processor and prereceive handling after …

c6da24b

…chain execution

docs: improve clearBareClone explanation, add plugin guide links, rem…

7fd31db

…ove todos

docs: update architecture diagram and set bg to white

5bf8f51

docs: add JWT api authentication guide

4ea9433

Merge branch 'main' into 1325-architecture-guide-draft

12e374a

Merge branch 'main' into 1325-architecture-guide-draft

783a262

Merge branch 'main' into 1325-architecture-guide-draft

6e2c8be

Update docs/Architecture.md

378c7f2

Co-authored-by: Fabio Vincenzi <93596376+fabiovincenzi@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

562c3b1

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

docs: proxy env variables configuration, add suggestions section

7fa4b29

jescalada and others added 18 commits February 11, 2026 12:10

Update docs/Architecture.md

232fce0

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

cd2099d

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

8e8a0a0

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

2f2966a

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

3402ccb

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

4c5d95b

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

ac48956

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

5548c15

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

addb952

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

43c20af

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

e4343f7

Co-authored-by: Kris West <kristopher.west@natwest.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

012d912

Co-authored-by: Thomas Cooper <57812123+coopernetes@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

04f241b

Co-authored-by: Thomas Cooper <57812123+coopernetes@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

Update docs/Architecture.md

48bbf14

Co-authored-by: Thomas Cooper <57812123+coopernetes@users.noreply.github.com> Signed-off-by: Juan Escalada <97265671+jescalada@users.noreply.github.com>

docs: add parseAction entry and pre-processors section

4e0382c

docs: improve checkUserPushPermission description, fix typos and wording

1be1975

docs: move processors into own file and update links

26a6e9c

docs: update architecture diagram, upload XML file for editing, add e…

c2ba9f4

…dit instructions

kriswest reviewed Feb 11, 2026

View reviewed changes

Merge branch 'main' into 1325-architecture-guide-draft

0c58883

coopernetes approved these changes Feb 12, 2026

View reviewed changes

Merge branch 'main' into 1325-architecture-guide-draft

978b04a

kriswest self-requested a review February 13, 2026 10:28

kriswest approved these changes Feb 13, 2026

View reviewed changes

This was referenced Feb 14, 2026

Unify repository and website documentation #1407

Open

Enable TLS for UI and API #1408

Open

jescalada merged commit 588d7f3 into main Feb 14, 2026
25 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: architecture guide#1391

docs: architecture guide#1391
jescalada merged 60 commits intomainfrom
1325-architecture-guide-draft

jescalada commented Feb 7, 2026

Uh oh!

jescalada commented Feb 11, 2026

Uh oh!

kriswest left a comment

Uh oh!

jescalada commented Feb 12, 2026

Uh oh!

coopernetes left a comment

Uh oh!

kriswest left a comment

Uh oh!

jescalada commented Feb 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

jescalada commented Feb 7, 2026

To-do

Uh oh!

jescalada commented Feb 11, 2026

Uh oh!

kriswest left a comment

Choose a reason for hiding this comment

Uh oh!

jescalada commented Feb 12, 2026

Uh oh!

coopernetes left a comment

Choose a reason for hiding this comment

Uh oh!

kriswest left a comment

Choose a reason for hiding this comment

Uh oh!

jescalada commented Feb 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants