Guide & Diagram Examples

Welcome to the PLANOVI internal documentation base. This site uses Docs-as-Code powered by Starlight (Astro) and is protected via Cloudflare Zero Trust.

Writing Markdown Docs

You can write documentation pages using standard Markdown or MDX (.md or .mdx files) and place them in the docs/src/content/docs/ directory.

Starlight automatically generates the page structure, layout, mobile responsiveness, and client-side page search.

Creating Diagrams with Mermaid.js

This documentation site has native support for Mermaid.js. To write a diagram, use the standard triple-backtick markdown code blocks with the language set to mermaid.

Architecture Flow

Here is a diagram representing how this docs site is hosted and secured:

graph TD
    User(["Developer / Team Member"]) -->|Access Website| Domain[docs.planovi.cooperative]
    Domain -->|Cloudflare DNS| CF_Access{Cloudflare Zero Trust}
    
    CF_Access -->|Not Authenticated| Login["Google / GitHub / OTP Login Page"]
    CF_Access -->|Authenticated & Allowed| CF_Pages[Cloudflare Pages Host]
    
    subgraph CF_Deployments ["Cloudflare Pages Deployments"]
        CF_Pages -->|Serves Static Files| DistFolder["Build Artifacts /dist"]
    end
    
    subgraph Dev_Pipeline ["Development Pipeline"]
        Repo[("GitHub / GitLab Repository")] -->|Git Push Event| CF_Build[CF Pages Build Pipeline]
        CF_Build -->|Runs 'npm run build'| DistFolder
    end

Authentication Logic Flow

Here is a sequence diagram representing the authorization verification logic:

sequenceDiagram
    autonumber
    actor Dev as Developer
    participant CF as Cloudflare Access Gate
    participant IdP as "Identity Provider (e.g. GitHub OAuth)"
    participant Origin as "Pages Origin (Internal Docs)"

    Dev->>CF: Request /guide/example/
    alt Session Token is Valid
        CF->>Origin: Forward Request
        Origin->>Dev: 200 OK (Render page)
    else Session Token is Expired / Missing
        CF->>Dev: Redirect to Identity Provider Login
        Dev->>IdP: Authenticate credentials
        IdP->>CF: Return Auth assertion token
        CF->>CF: Verify user email matches @domain policy
        CF->>Dev: Set cf-access-jwt-assertion cookie
        CF->>Origin: Forward Request
        Origin->>Dev: 200 OK (Render page)
    end

---

Adding Your Content

To begin writing your documentation:

1. Place your .md files in docs/src/content/docs/.
2. To organize pages in folders, create folders like docs/src/content/docs/infrastructure/ or docs/src/content/docs/database/.
3. Update the sidebar configuration in docs/astro.config.mjs to list your new pages, or use the autogenerate configuration to automatically list files in a folder.