# kant-righteous/franchina architecture

> Architecture diagram of the GitHub repository kant-righteous/franchina, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kant-righteous/franchina
- Repository: https://github.com/kant-righteous/franchina
- Video tour (about a minute): https://gitdiagram.com/kant-righteous/franchina/video

## Overview

FranChina is a French-life information site for Chinese students, with a separate Remote MCP service for exchange-rate data. The main reader journey is browsing topic and city guides; the service journey accepts authenticated rate submissions and stores them. The README documents additional guide categories and tools that are represented by their existing content directories. MCP excerpts establish the server, persistence, and authentication components; unsampled site rendering and some MCP wiring are shown only where documented.

Main entry points: [`docs/index.md`](https://github.com/kant-righteous/franchina/blob/main/docs/index.md) (FranChina website), [`mcp/franchina_mcp/server.py`](https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/server.py) (MCP server), [`scripts/update_currency.py`](https://github.com/kant-righteous/franchina/blob/main/scripts/update_currency.py) (Currency updater), [`mcp/franchina_mcp/api_keys.py`](https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/api_keys.py) (API key auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guides["Student Guides"]
  node_guide_content["Guide content"]
  node_guide_assets["Guide assets"]
  node_admin_guides["Admin guides"]
  node_life_guides["Life guides"]
  node_city_guides["City guides"]
  node_toulouse_guides["Toulouse guides"]
  node_help_tools["Help and tools"]
end

subgraph group_site["Website Presentation"]
  node_site_config["Site configuration<br/>[mkdocs.yml]"]
  node_theme_override["Theme override<br/>[main.html]"]
  node_site_styles["Site styles"]
  node_website["FranChina website<br/>[index.md]"]
end

subgraph group_mcp["Remote MCP"]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_api_auth["API key auth<br/>[api_keys.py]"]
  node_access_auth["Access auth"]
  node_request_gate["Request gate<br/>[public_gate.py]"]
  node_auth_db[("Auth database<br/>[api_keys.py]")]
  node_key_admin["Key management<br/>[keys.py]"]
end

subgraph group_rates["Rate Data"]
  node_rate_models["Rate validation<br/>[models.py]"]
  node_rate_repository["Rates repository<br/>[database.py]"]
  node_rates_db[("Rates database<br/>[database.py]")]
  node_currency_update["Currency updater<br/>[update_currency.py]"]
  node_currency_assets["Currency data assets"]
end

node_reader(("Student reader"))
node_mcp_client(("MCP client"))
node_cloudflare["Cloudflare Access"]
node_rate_source["Exchange-rate source"]

node_reader -->|"browses"| node_website
node_guide_content -->|"provides content"| node_website
node_guide_assets -->|"supplies media"| node_website
node_site_config -->|"configures"| node_website
node_theme_override -->|"customizes"| node_website
node_site_styles -->|"styles"| node_website
node_mcp_client -->|"calls tools"| node_mcp_server
node_mcp_server -->|"validates input"| node_rate_models
node_mcp_server -->|"saves rates"| node_rate_repository
node_rate_repository -->|"reads and writes"| node_rates_db
node_mcp_server -.->|"uses in API-key mode"| node_api_auth
node_mcp_server -.->|"uses in Access mode"| node_access_auth
node_api_auth -->|"gates requests"| node_request_gate
node_access_auth -->|"gates requests"| node_request_gate
node_api_auth -->|"looks up keys"| node_auth_db
node_key_admin -->|"manages keys"| node_auth_db
node_cloudflare -.->|"provides assertions"| node_access_auth
node_currency_update -->|"fetches rates"| node_rate_source
node_currency_update -->|"updates files"| node_currency_assets
node_currency_update -.->|"backfills history"| node_guide_assets

click node_guide_content "https://github.com/kant-righteous/franchina/tree/main/docs/pages"
click node_guide_assets "https://github.com/kant-righteous/franchina/tree/main/docs/assets"
click node_admin_guides "https://github.com/kant-righteous/franchina/tree/main/docs/pages/admin"
click node_life_guides "https://github.com/kant-righteous/franchina/tree/main/docs/pages/life"
click node_city_guides "https://github.com/kant-righteous/franchina/tree/main/docs/pages/cities"
click node_toulouse_guides "https://github.com/kant-righteous/franchina/tree/main/docs/pages/toulouse"
click node_help_tools "https://github.com/kant-righteous/franchina/tree/main/docs/pages/help"
click node_site_config "https://github.com/kant-righteous/franchina/blob/main/mkdocs.yml"
click node_theme_override "https://github.com/kant-righteous/franchina/blob/main/overrides/main.html"
click node_site_styles "https://github.com/kant-righteous/franchina/tree/main/docs/stylesheets"
click node_website "https://github.com/kant-righteous/franchina/blob/main/docs/index.md"
click node_mcp_server "https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/server.py"
click node_rate_models "https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/models.py"
click node_rate_repository "https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/database.py"
click node_rates_db "https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/database.py"
click node_api_auth "https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/api_keys.py"
click node_access_auth "https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/cloudflare_access.py"
click node_request_gate "https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/public_gate.py"
click node_auth_db "https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/api_keys.py"
click node_key_admin "https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/keys.py"
click node_currency_update "https://github.com/kant-righteous/franchina/blob/main/scripts/update_currency.py"
click node_currency_assets "https://github.com/kant-righteous/franchina/tree/main/docs/assets/life/finance/currency-calculator"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_guide_content,node_guide_assets,node_admin_guides,node_life_guides,node_city_guides,node_toulouse_guides,node_help_tools,node_mcp_client toneBlue
class node_site_config,node_theme_override,node_site_styles,node_website toneAmber
class node_mcp_server,node_api_auth,node_access_auth,node_request_gate,node_auth_db,node_key_admin toneMint
class node_rate_models,node_rate_repository,node_rates_db,node_currency_update,node_currency_assets toneRose
class node_reader,node_cloudflare,node_rate_source toneIndigo
```

## Components

### Student Guides

- [Guide content](https://github.com/kant-righteous/franchina/tree/main/docs/pages): `docs/pages`
- [Guide assets](https://github.com/kant-righteous/franchina/tree/main/docs/assets): `docs/assets`
- [Admin guides](https://github.com/kant-righteous/franchina/tree/main/docs/pages/admin): `docs/pages/admin`
- [Life guides](https://github.com/kant-righteous/franchina/tree/main/docs/pages/life): `docs/pages/life`
- [City guides](https://github.com/kant-righteous/franchina/tree/main/docs/pages/cities): `docs/pages/cities`
- [Toulouse guides](https://github.com/kant-righteous/franchina/tree/main/docs/pages/toulouse): `docs/pages/toulouse`
- [Help and tools](https://github.com/kant-righteous/franchina/tree/main/docs/pages/help): `docs/pages/help`

### Website Presentation

- [Site configuration](https://github.com/kant-righteous/franchina/blob/main/mkdocs.yml): `mkdocs.yml`
- [Theme override](https://github.com/kant-righteous/franchina/blob/main/overrides/main.html): `overrides/main.html`
- [Site styles](https://github.com/kant-righteous/franchina/tree/main/docs/stylesheets): `docs/stylesheets`
- [FranChina website](https://github.com/kant-righteous/franchina/blob/main/docs/index.md): `docs/index.md`

### Remote MCP

- [MCP server](https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/server.py): `mcp/franchina_mcp/server.py`
- [API key auth](https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/api_keys.py): `mcp/franchina_mcp/api_keys.py`
- [Access auth](https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/cloudflare_access.py): `mcp/franchina_mcp/cloudflare_access.py`
- [Request gate](https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/public_gate.py): `mcp/franchina_mcp/public_gate.py`
- [Auth database](https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/api_keys.py): `mcp/franchina_mcp/api_keys.py`
- [Key management](https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/keys.py): `mcp/franchina_mcp/keys.py`

### Rate Data

- [Rate validation](https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/models.py): `mcp/franchina_mcp/models.py`
- [Rates repository](https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/database.py): `mcp/franchina_mcp/database.py`
- [Rates database](https://github.com/kant-righteous/franchina/blob/main/mcp/franchina_mcp/database.py): `mcp/franchina_mcp/database.py`
- [Currency updater](https://github.com/kant-righteous/franchina/blob/main/scripts/update_currency.py): `scripts/update_currency.py`
- [Currency data assets](https://github.com/kant-righteous/franchina/tree/main/docs/assets/life/finance/currency-calculator): `docs/assets/life/finance/currency-calculator`

### Other components

- **Student reader**
- **MCP client**
- **Cloudflare Access**
- **Exchange-rate source**

## Connections

- Student reader → FranChina website: browses
- Guide content → FranChina website: provides content
- Guide assets → FranChina website: supplies media
- Site configuration → FranChina website: configures
- Theme override → FranChina website: customizes
- Site styles → FranChina website: styles
- MCP client → MCP server: calls tools
- MCP server → Rate validation: validates input
- MCP server → Rates repository: saves rates
- Rates repository → Rates database: reads and writes
- MCP server → API key auth: uses in API-key mode
- MCP server → Access auth: uses in Access mode
- API key auth → Request gate: gates requests
- Access auth → Request gate: gates requests
- API key auth → Auth database: looks up keys
- Key management → Auth database: manages keys
- Cloudflare Access → Access auth: provides assertions
- Currency updater → Exchange-rate source: fetches rates
- Currency updater → Currency data assets: updates files
- Currency updater → Guide assets: backfills history