# instinctbits/astro-datanova architecture

> Architecture diagram of the GitHub repository instinctbits/astro-datanova, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/instinctbits/astro-datanova
- Repository: https://github.com/instinctbits/astro-datanova

## Overview

##### Project type and purpose
- This is a full-stack, multi-page website template (“DataNova”) built with Astro. It serves marketing sites, docs hubs, and dynamic applications.
- Key features: SSR pages, static asset delivery, content collections (Markdoc), Keystatic CMS for content editing, Astro DB + Turso for data (feedback), Tailwind CSS + Preline UI for styling.

##### File structure
- Top-level:
- db/ – defines Astro DB schema (`db/config.ts`) and seeds (`db/seed.ts`).
- public/ – static assets served as-is (images, manifest).
- src/ – application code:
– assets/ (images, global styles)
– content.config.ts + content/ (Markdoc articles & reference)
– data/ (JSON collections)
– layout/ (BaseLayout.astro)
– pages/ – routing: SSR pages (index.astro, about.astro, contact.astro), dynamic support routes, API route (`pages/api/feedback.ts`), robots.txt.
– utils/ – nav, megaMenu, helpers
- config files: astro.config.mjs (integrations: React, Markdoc, Keystatic, Astro DB, adapter), tsconfig.json, svelte.config.js, vercel.json, .env.template.
- Architectural patterns:
- Server-Side Rendering (SSR) via Astro adapter on Vercel
- Content-driven: file-based routing + Markdoc collections + Keystatic admin UI
- API layer: single feedback endpoint writing to Astro DB/Turso
- Utility modules for navigation & mega menus

##### README for additional insights
- Integrations: Astro SEO, Astro Font, ClientRouter (view transitions), optional sitemap
- Deployment: Vercel SSR with environment variables for Astro DB & Keystatic
- Customization: navigation/megaMenu via utils, footers via layout import swap

a. Main components:
- Client (Browser)
- CDN / Static Assets (public/, Tailwind-built CSS, images)
- Astro SSR Server (Vercel)
– Routing Layer (file-based pages under src/pages)
– Markdoc Renderer (content.config.ts + src/content)
– API Layer (`/api/feedback.ts`)
– Keystatic CMS Admin UI (`/keystatic`)
– Integrations: Astro SEO, Astro Font, ClientRouter
- Database (Astro DB → Turso remote)
- GitHub (optional content storage for Keystatic in “github” mode)
- Dev Tools (local filesystem for Markdoc + Keystatic local mode)
b. Relationships & flows:
1. Browser → SSR Server: request pages → Astro reads content (local or GitHub via Keystatic) + JSON data → renders HTML + inlined CSS/JS → returns to client
3. Browser → API `/api/feedback`: fetch POST → SSR Server writes to Astro DB → pushes to Turso
4. Admin Editor ↔ Keystatic UI → reads/writes Markdoc files (local FS or GitHub repo) via SSR Server
5. SSR Server ↔ Turso: runs queries over Astro DB integration
6. CI/CD: GitHub → Vercel auto-deploy → environment variables set for SSR & DB
c. Architectural patterns & principles:
- Separation of concerns: clear static vs dynamic routes; content vs presentation vs data
- File-based routing for pages and API
- Content collections for scalability (articles, reference, data JSON)
- Single-responsibility components (common vs sections vs ui)
- Pluggable integrations for SEO, fonts, CMS, DB
d. Key technologies:
- Astro (core SSR & static builder)
- Tailwind CSS + Preline UI (styles, interactive UI)
- Markdoc (content authoring)
- Keystatic (CMS integration)
- Astro DB + Turso (feedback storage)
- Vercel adapter (deployment)
- Svelte (feedback component)

##### Capturing essential architectural elements
- You include every boundary: static assets CDN vs SSR dynamic, CMS UI routes vs public pages, API route vs page routes
- Don’t over-compartmentalize—focus on the six or seven primary blocks listed above for clarity.

## Diagram (Mermaid)

```mermaid
graph TD
    Browser["Browser"]

    subgraph CDN["CDN / Static Assets"]
        Public["public/"]:::http
        Assets["src/assets/"]:::http
    end

    subgraph "Astro SSR Server"
        Routing["SSR Routing Layer"]:::http
        MarkdocConfig["Markdoc Config"]:::cms
        MarkdocContent["Markdoc Content"]:::cms
        API["API Layer (/api/feedback)"]:::api
        CMS["Keystatic CMS Admin UI"]:::cms
        Layout["Layout Component"]:::http
        UIComp["UI Components"]:::http
        JSONData["JSON Data Collections"]:::data
        Utils["Utility Modules"]:::http
        Integrations["Astro Config & Integrations"]:::http
        Styles["Global Styles"]:::http
    end

    subgraph "Data Layer"
        AstroDB["Astro DB + Turso"]:::data
        GitHub["GitHub Repo"]:::data
        Vercel["Vercel (Deployment)"]:::external
    end

    subgraph "Admin"
        Admin["Admin Editor"]:::external
    end

    Browser -->|"HTTP Page Request"| Routing
    Browser -->|"HTTP Page Request"| Public
    Browser -->|"HTTP Page Request"| Assets
    Browser -->|"Fetch POST /api/feedback"| API

    Routing -->|"renders using"| MarkdocConfig
    Routing -->|"renders using"| MarkdocContent
    Routing -->|"wraps with"| Layout
    Routing -->|"uses UI Components"| UIComp
    Routing -->|"loads JSON"| JSONData
    Routing -->|"uses Utilities"| Utils
    Routing -->|"applies Styles"| Styles

    API -->|"writes to"| AstroDB
    Routing -->|"queries"| AstroDB

    Admin -->|"edits content"| CMS
    CMS -->|"reads/writes"| MarkdocContent
    CMS -->|"reads/writes"| MarkdocConfig
    GitHub -.->|".optional"| CMS

    GitHub -->|"push code"| Vercel
    Vercel -->|"deploys SSR"| Routing

    SSRIntegrations[("Integrations\n(SEO, Fonts,\nAdapter, DB)")]:::http
    Routing -->|"configured by"| SSRIntegrations

    classDef http fill:#cce5ff,stroke:#66b,color:#004085
    classDef api fill:#d4edda,stroke:#28a745,color:#155724
    classDef cms fill:#fff3cd,stroke:#ffc107,color:#856404
    classDef data fill:#e2e3e5,stroke:#6c757d,color:#383d41
    classDef external fill:#f0f0f0,stroke:#999,color:#333

    click Routing "https://github.com/instinctbits/astro-datanova/tree/main/src/pages/"
    click Public "https://github.com/instinctbits/astro-datanova/tree/main/public/"
    click Assets "https://github.com/instinctbits/astro-datanova/tree/main/src/assets/"
    click MarkdocConfig "https://github.com/instinctbits/astro-datanova/blob/main/src/content.config.ts"
    click MarkdocContent "https://github.com/instinctbits/astro-datanova/tree/main/src/content/"
    click CMS "https://github.com/instinctbits/astro-datanova/blob/main/keystatic.config.ts"
    click API "https://github.com/instinctbits/astro-datanova/blob/main/src/pages/api/feedback.ts"
    click AstroDB "https://github.com/instinctbits/astro-datanova/blob/main/db/config.ts"
    click Layout "https://github.com/instinctbits/astro-datanova/blob/main/src/layout/BaseLayout.astro"
    click UIComp "https://github.com/instinctbits/astro-datanova/tree/main/src/components/"
    click JSONData "https://github.com/instinctbits/astro-datanova/tree/main/src/data/"
    click Utils "https://github.com/instinctbits/astro-datanova/tree/main/src/utils/"
    click Integrations "https://github.com/instinctbits/astro-datanova/blob/main/astro.config.mjs"
    click Styles "https://github.com/instinctbits/astro-datanova/blob/main/src/assets/styles/global.css"
```
