Skip to content

Commit b3c1385

Browse files
committed
docs: add Architecture section, update Process, add Weekplanner docs
- New Architecture section with ecosystem overview, systems table, shared JWT auth, repository map - 4 seed ADRs (shared JWT, DB-first VTA, split repos foodplanner, docs split) - New branch-strategy.md replacing GitFlow with trunk-based development - Updated code_workflow.md to remove GitFlow references - New Weekplanner development guide - Added CONTRIBUTING.md and CODEOWNERS - Redirected old architecture.md to new Architecture section - Updated navigation and index - Added search exclusion for Archive
1 parent 729e288 commit b3c1385

File tree

19 files changed

+308
-124
lines changed

19 files changed

+308
-124
lines changed

.github/CODEOWNERS

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* @aau-giraf/maintainers

CONTRIBUTING.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Contributing to the GIRAF Wiki
2+
3+
For general workflow and guidelines, see the [organization CONTRIBUTING.md](https://github.com/aau-giraf/.github/blob/main/CONTRIBUTING.md).
4+
5+
## Development Setup
6+
7+
### Prerequisites
8+
9+
- Python 3.x
10+
- pip
11+
12+
### Local Development
13+
14+
```bash
15+
pip install mkdocs-material mkdocs-awesome-pages-plugin
16+
mkdocs serve # Dev server at localhost:8000
17+
```
18+
19+
### Page Conventions
20+
21+
- Each section has an `index.md` as its landing page
22+
- Use `.pages` files to control navigation order
23+
- Place images in `docs/resources/`
24+
25+
### Creating Pages
26+
27+
1. Add your `.md` file in the appropriate section under `docs/`
28+
2. Update the section's `.pages` file to include it
29+
3. Verify with `mkdocs build` — should produce zero warnings

docs/.pages

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ arrange:
33
- ...
44
- Onboarding
55
- Process
6+
- Architecture
67
- Development
78
- Legal
89
- About

docs/Architecture/.pages

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
arrange:
2+
- index.md
3+
- decisions

docs/Architecture/decisions/.pages

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
arrange:
2+
- TEMPLATE.md
3+
- ...
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# 1. Shared JWT Auth
2+
3+
**Date:** 2025-01-01
4+
5+
**Status:** accepted
6+
7+
## Context
8+
9+
Multiple app backends need to authorize requests from users who authenticate with Core. Calling Core on every request adds latency and a single point of failure.
10+
11+
## Decision
12+
13+
Core issues JWTs with an `org_roles` claim. All backends validate locally using a shared `JWT_SECRET` (HS256). Role hierarchy: owner > admin > member.
14+
15+
## Consequences
16+
17+
Backends authorize without network calls. Adding a new backend only requires the shared secret. Revoking access requires token expiry (no instant revocation). Secret rotation requires coordinated deployment.
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# 2. DB-First for VTA
2+
3+
**Date:** 2025-01-01
4+
5+
**Status:** accepted
6+
7+
## Context
8+
9+
VTA's database schema predates the current .NET backend. Schema changes are designed in MySQL directly by developers familiar with SQL.
10+
11+
## Decision
12+
13+
Use DB-first with `dotnet ef dbcontext scaffold` instead of code-first migrations. `mysql_schema.sql` is the schema source of truth.
14+
15+
## Consequences
16+
17+
Schema changes are explicit SQL. No migration conflicts. Developers must scaffold after schema changes. Can't use EF migration tooling for rollbacks.
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# 3. Split Repos for Foodplanner
2+
3+
**Date:** 2025-01-01
4+
5+
**Status:** accepted
6+
7+
## Context
8+
9+
Foodplanner frontend (Flutter) and backend (.NET) have different CI pipelines, dependencies, and deployment targets.
10+
11+
## Decision
12+
13+
Separate repos (`foodplanner` for frontend, `foodplanner-api` for backend). VTA keeps its monorepo since frontend and backend are tightly coupled (SignalR real-time sync).
14+
15+
## Consequences
16+
17+
Independent CI/CD per component. Separate versioning. API contract changes require coordinated PRs across repos.
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# 4. Docs: Wiki + Website
2+
3+
**Date:** 2025-01-01
4+
5+
**Status:** accepted
6+
7+
## Context
8+
9+
GIRAF needs both contributor-facing technical docs and a public-facing project site. MkDocs suits structured technical docs; Jekyll suits blog-style public content.
10+
11+
## Decision
12+
13+
MkDocs wiki (`aau-giraf/wiki`) for contributor docs. Jekyll website (`GIRAF-website`) for public project information.
14+
15+
## Consequences
16+
17+
Two doc systems to maintain. Clear audience separation. Contributors use markdown in wiki repo. Public content managed separately.
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# [NUMBER]. [TITLE]
2+
3+
**Date:** YYYY-MM-DD
4+
5+
**Status:** [proposed | accepted | deprecated | superseded by [ADR-NNNN](NNNN-*.md)]
6+
7+
## Context
8+
9+
[What is the issue that we're seeing that is motivating this decision or change?]
10+
11+
## Decision
12+
13+
[What is the change that we're proposing and/or doing?]
14+
15+
## Consequences
16+
17+
[What becomes easier or more difficult to do because of this change?]

0 commit comments

Comments
 (0)