Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,9 @@ Public HTTPS hosting on a free Oracle VM: [deployment guide](deploy/README.md).

## Documentation

- [Implemented system logic and mathematical audit](docs/architecture/system-logic.md): modes,
configuration, travel-time formulas, signal state machines and implementation limitations.

- [GreenWave_ARCHITECTURE.md](GreenWave_ARCHITECTURE.md): system design and API.
- [docs/adr/](docs/adr/README.md): architecture decisions and their status.
- [backend/README.md](backend/README.md): ETL, simulation settings, simulated ITS feedback.
Expand All @@ -127,7 +130,8 @@ Public HTTPS hosting on a free Oracle VM: [deployment guide](deploy/README.md).
its workspace controls.
- [CONTRIBUTING.md](CONTRIBUTING.md): checks, branches, commits and contract changes.
- The in-app **Documentation** page (`/docs`): the Open Data App contest write-up in Polish and
English (project, running it, technologies, data, architecture, future development).
English (project, technologies, data, architecture, details, future development).
The **Details** tab at `/docs#details` contains the core formulas, parameter reference and state machines.

## Data sources and attribution

Expand Down
936 changes: 936 additions & 0 deletions docs/architecture/system-logic.md

Large diffs are not rendered by default.

18 changes: 14 additions & 4 deletions docs/engineering/frontend-dashboard.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,10 +61,10 @@ camera actions stop an old gesture before applying the new view so rapid toggles

## Documentation page

`/docs` holds the contest documentation (Open Data App rules §5.2) as six tabs: About, Running it,
Technologies, Data, Architecture, Future development. The copy lives in
`src/lib/docs/content.ts` as typed blocks per language and does not go through the `polish.ts`
dictionary. PL and EN must stay structurally identical, every command must appear in `README.md`,
`/docs` holds the contest documentation (Open Data App rules §5.2) as six tabs: About, Technologies,
Data, Architecture, Details, Future development. The copy lives in
`src/lib/docs/content.ts` and `details-content.ts` as typed blocks per language and does not
go through the `polish.ts` dictionary. PL and EN must stay structurally identical, every command must appear in `README.md`,
and English sentences must not copy the repository docs (`content.test.ts`,
`content-facts.test.ts`). The active tab is the URL hash (`/docs#data`), with unknown hashes
opening About, and the tabs follow the WAI-ARIA tabs keyboard model.
Expand All @@ -75,3 +75,13 @@ full-width tables and diagrams; a section marked `numbered` numbers its headings
table marked `cards` renders one card per row. Behind it sits the home corridor in road ink (no
signal colours). The tab track sticks under the header and turns glass only while stuck; one thumb
slides to the clicked tab and the panel fades in, while keyboard switches stay instant.

Architecture covers ownership, modes, the per-second step and the run lifecycle. The Details tab
(`/docs#details`; the former `#logic` hash still opens it) holds the implementation reference in
both languages: configuration, parameters, movement and signal rules, and model limits. Keep it to
the few core formulas. Formula blocks use compact notation (`x_i`, `t_{a,e}`, `x^2`) typeset by
`MathNotation` in the route-scoped STIX Two Text face. Lifecycles and pipelines are `flow` blocks
(steps, dashed branches, an optional cycle), never preformatted text. `details-settings.ts` stores
the audited parameter reference values, not runtime configuration. Keep it aligned with the audited
backend settings and ETL constants when updating that reference. A footer on every tab credits the
authors with their GitHub profiles.
12 changes: 11 additions & 1 deletion frontend/src/app/docs/page.tsx
Original file line number Diff line number Diff line change
@@ -1,8 +1,18 @@
import { STIX_Two_Text } from "next/font/google";
import { pageMetadata } from "@/lib/localized-metadata";
import { DocsWorkspace } from "@/components/docs/DocsWorkspace";

/** Formula typeface, loaded only for the documentation route. */
const mathFont = STIX_Two_Text({
variable: "--font-math",
subsets: ["latin", "greek"],
style: ["normal", "italic"],
preload: false,
});

export async function generateMetadata() {
return pageMetadata("Documentation");
}
export default function Page() {
return <DocsWorkspace />;
return <DocsWorkspace className={mathFont.variable} />;
}
190 changes: 190 additions & 0 deletions frontend/src/app/globals.css
Original file line number Diff line number Diff line change
Expand Up @@ -3156,6 +3156,151 @@ a.docs-chip:focus-visible,
font-weight: 500;
color: var(--muted-foreground);
}
.docs-notation {
min-width: 0;
max-width: 100%;
border: 1px solid var(--border);
border-radius: var(--radius-card);
background: var(--card);
overflow: hidden;
}
.docs-notation figcaption {
padding: 0.625rem 0.875rem;
font-size: 0.8125rem;
font-weight: 600;
background: var(--muted);
}
/* Formulas read as mathematics: a text serif, italic variables and real scripts. */
.docs-math {
display: grid;
gap: 0.375rem;
max-width: 100%;
overflow-x: auto;
padding: 0.875rem 1rem;
font-family: var(--font-math), "STIX Two Text", "Cambria Math", Cambria, "Times New Roman", serif;
font-size: 1.0625rem;
line-height: 1.6;
font-variant-numeric: lining-nums;
}
.docs-math-line {
white-space: nowrap;
}
.docs-math var {
font-style: italic;
}
.docs-math sub,
.docs-math sup {
font-size: 0.7em;
line-height: 0;
}
.docs-math:focus-visible {
outline: 2px solid var(--ring);
outline-offset: -2px;
}

/* Flows share the architecture diagram's boxes: solid steps, dashed side outcomes. */
.docs-flow {
container-type: inline-size;
display: grid;
gap: 0.75rem;
max-width: 54rem;
}
.docs-flow figcaption {
font-size: 0.8125rem;
font-weight: 600;
}
.docs-flow-steps {
display: flex;
flex-direction: column;
gap: 0.25rem;
list-style: none;
}
.docs-flow-step {
display: flex;
flex-direction: column;
min-width: 0;
}
.docs-flow-arrow {
align-self: center;
flex: none;
width: 1rem;
height: 1rem;
margin-bottom: 0.25rem;
color: var(--muted-foreground);
transform: rotate(90deg);
}
.docs-flow-column {
flex: 1;
min-width: 0;
}
.docs-flow-node {
display: grid;
gap: 0.125rem;
padding: 0.625rem 0.75rem;
border: 1px solid color-mix(in oklch, var(--muted-foreground) 50%, transparent);
border-radius: 10px;
background: var(--card);
font-size: 0.8125rem;
line-height: 1.35;
}
.docs-flow-node strong {
font-weight: 600;
overflow-wrap: anywhere;
}
.docs-flow-node span {
font-size: 0.75rem;
color: var(--muted-foreground);
}
.docs-flow-node-branch {
border-style: dashed;
background: transparent;
}
.docs-flow-branches {
display: grid;
gap: 0.375rem;
margin-top: 0.375rem;
list-style: none;
}
.docs-flow-branches li {
display: flex;
align-items: flex-start;
gap: 0.25rem;
}
.docs-flow-branches .docs-flow-node {
flex: 1;
min-width: 0;
}
.docs-flow-branch-arrow {
flex: none;
width: 0.875rem;
height: 0.875rem;
margin-top: 0.625rem;
color: var(--muted-foreground);
}
.docs-flow-cycle {
display: flex;
align-items: center;
gap: 0.5rem;
font-size: 0.8125rem;
color: var(--muted-foreground);
}
@container (min-width: 40rem) {
.docs-flow-steps {
flex-direction: row;
align-items: flex-start;
}
.docs-flow-step {
flex: 1 1 0;
flex-direction: row;
align-items: flex-start;
gap: 0.25rem;
}
.docs-flow-arrow {
align-self: flex-start;
margin: 1.25rem 0 0;
transform: none;
}
}
.docs-group .docs-code {
background: var(--tile);
}
Expand Down Expand Up @@ -3396,6 +3541,51 @@ a.docs-chip:focus-visible,
grid-row: auto;
}
}
/* Credits close every tab: authors' GitHub profiles, the repository and the simulation notice. */
.docs-footer {
display: flex;
flex-wrap: wrap;
gap: 1.25rem 3rem;
margin-top: 4rem;
padding-top: 1.5rem;
border-top: 1px solid var(--border);
font-size: 0.875rem;
}
.docs-footer h2 {
font-size: 0.75rem;
font-weight: 600;
letter-spacing: 0.02em;
color: var(--muted-foreground);
}
.docs-footer ul {
display: flex;
flex-wrap: wrap;
gap: 0 1.5rem;
list-style: none;
}
.docs-footer a {
display: inline-flex;
align-items: center;
gap: 0.4375rem;
min-height: 44px;
text-decoration: underline;
text-underline-offset: 4px;
text-decoration-color: color-mix(in srgb, var(--beacon) 35%, transparent);
}
.docs-footer a:focus-visible {
outline: 2px solid var(--ring);
outline-offset: 3px;
}
.docs-footer-handle {
font-family: var(--font-mono);
font-size: 0.75rem;
color: var(--muted-foreground);
}
.docs-footer-notice {
flex-basis: 100%;
font-size: 0.8125rem;
color: var(--muted-foreground);
}
.docs-panel:focus-visible {
outline: 2px solid var(--ring);
outline-offset: 6px;
Expand Down
1 change: 1 addition & 0 deletions frontend/src/app/page-titles.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import { generateMetadata as standard } from "./simulation/standard/page";
vi.mock("next/font/google", () => ({
Geist: () => ({ variable: "" }),
Geist_Mono: () => ({ variable: "" }),
STIX_Two_Text: () => ({ variable: "" }),
}));

it("names each workspace in the browser title", async () => {
Expand Down
11 changes: 11 additions & 0 deletions frontend/src/components/docs/DocsBlocks.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@ import { Info } from "lucide-react";
import type { DocsBlock } from "@/lib/docs/content";
import { ArchitectureDiagram } from "./ArchitectureDiagram";
import { CodeBlock } from "./CodeBlock";
import { FlowDiagram } from "./FlowDiagram";
import { MathNotation } from "./MathNotation";

export function Block({ block }: { block: DocsBlock }) {
switch (block.kind) {
Expand Down Expand Up @@ -73,6 +75,15 @@ export function Block({ block }: { block: DocsBlock }) {
</div>
</div>
);
case "formula":
return (
<figure className="docs-notation">
<figcaption>{block.label}</figcaption>
<MathNotation expression={block.expression} />
</figure>
);
case "flow":
return <FlowDiagram label={block.label} steps={block.steps} cycle={block.cycle} />;
case "code":
return <CodeBlock label={block.label} code={block.code} />;
case "links":
Expand Down
32 changes: 32 additions & 0 deletions frontend/src/components/docs/DocsFooter.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
import { ArrowUpRight } from "lucide-react";
import type { Language } from "@/lib/localization";
import { DOCS_AUTHORS, DOCS_REPOSITORY, docsFooter } from "@/lib/docs/content";

/** Credits shared by every docs tab: authors' GitHub profiles and the repository. */
export function DocsFooter({ language }: { language: Language }) {
const copy = docsFooter[language];
return (
<footer className="docs-footer">
<div className="docs-footer-group">
<h2>{copy.authors}</h2>
<ul>
{DOCS_AUTHORS.map(({ name, github }) => (
<li key={github}>
<a href={`https://github.com/${github}`} target="_blank" rel="noopener">
{name}
<span className="docs-footer-handle">@{github}</span>
</a>
</li>
))}
</ul>
</div>
<div className="docs-footer-group">
<h2>{copy.repository}</h2>
<a href={DOCS_REPOSITORY} target="_blank" rel="noopener">
fjarmula/GreenWave <ArrowUpRight aria-hidden className="size-4 shrink-0" />
</a>
</div>
<p className="docs-footer-notice">{copy.notice}</p>
</footer>
);
}
21 changes: 6 additions & 15 deletions frontend/src/components/docs/DocsWorkspace.tsx
Original file line number Diff line number Diff line change
@@ -1,18 +1,19 @@
"use client";
import { useTranslation } from "@/components/language-provider";
import { useEffect, useRef } from "react";
import { ArrowUpRight } from "lucide-react";
import { ThemeToggle } from "@/components/hud/ThemeToggle";
import { ResponsiveNavigation } from "@/components/workspace/ResponsiveNavigation";
import { WorkspaceHeader } from "@/components/workspace/WorkspaceHeader";
import { useIsPhone } from "@/lib/useIsPhone";
import { DEMO_URL, docsContent } from "@/lib/docs/content";
import { docsContent } from "@/lib/docs/content";
import { DocsBackdrop } from "./DocsBackdrop";
import { DocsFooter } from "./DocsFooter";
import { DocsSectionView } from "./DocsSectionView";
import { DocsTabs } from "./DocsTabs";
import { useDocsSection } from "./useDocsSection";

export function DocsWorkspace() {
/** `className` carries the route-scoped math font variable. */
export function DocsWorkspace({ className }: { className?: string }) {
const { t, language } = useTranslation();
const phone = useIsPhone();
const [active, select] = useDocsSection();
Expand All @@ -31,7 +32,7 @@ export function DocsWorkspace() {
const sections = docsContent[language];
const section = sections.find((item) => item.id === active) ?? sections[0];
return (
<main className="home-main content-page docs-page">
<main className={["home-main content-page docs-page", className].filter(Boolean).join(" ")}>
<DocsBackdrop />
<WorkspaceHeader variant="page" compact={phone} actions={!phone && <ThemeToggle />}>
<ResponsiveNavigation current="/docs" title={t("Documentation")} heading={false} />
Expand All @@ -46,17 +47,6 @@ export function DocsWorkspace() {
<span aria-hidden="true" className="size-1.5 shrink-0 rounded-full bg-amber-500" />
{t("Simulation mode")}
</span>
<a className="docs-chip" href={DEMO_URL} target="_blank" rel="noopener">
{t("Live demo")} <ArrowUpRight aria-hidden className="size-4 shrink-0" />
</a>
<a
className="docs-chip"
href="https://github.com/fjarmula/GreenWave"
target="_blank"
rel="noopener"
>
GitHub <ArrowUpRight aria-hidden className="size-4 shrink-0" />
</a>
</div>
</div>
<div className="docs-layout">
Expand All @@ -80,6 +70,7 @@ export function DocsWorkspace() {
<DocsSectionView section={section} />
</section>
</div>
<DocsFooter language={language} />
</main>
);
}
Loading
Loading