squid 5897f118b9 BLOG-49 Add git convention and architecture documentation (#327)
### Description

- Add `docs/git-convention.md`: ticket prefixes, commit message and branch naming, PR
  title and body requirements, what CI enforces, and a pre-push checklist.
- Add `docs/architecture.md`: the Clean Architecture layers the Rust backend and the
  SvelteKit frontend share, a request traced through each layer, the composition roots,
  error handling, persistence, runtime wiring, coding conventions, and an add-a-feature
  checklist.
- Add the `docs-consistency` agent skill so that drift between `docs/` and the
  implementation is either fixed deliberately or raised with the user, instead of
  silently accumulating.
- Switch the `create-pr` agent skill from `tea` to the `gt` Gitea CLI, recording the
  flags that matter in practice (`--no-input`, `-R`, `-F`, `--yes` only for an agreed
  push) and how to read `gt auth status`.
- Point the README at `docs/` now that developer documentation lives in the repository
  rather than the wiki, and drop the unused MCP server setup section.
- Correct the backend README, which still described authentication as JWT-based although
  it uses OIDC with Redis-backed sessions.
- Reformat the `backend/Cargo.toml` dependency tables; no dependency, version, or feature
  changes.

### Package Changes

None

### Screenshots

None

### Reference

Resolves #49

### Checklist

- [x] A milestone is set
- [x] The related issues has been linked to this branch

Reviewed-on: #327
Co-authored-by: SquidSpirit <squid@squidspirit.com>
2026-11-04 00:11:29 +08:00
2026-09-24 16:12:47 +08:00

Blog

Description

  • Frontend: SvelteKit with Tailwind CSS
  • Backend: Rust actix-web

Despite SvelteKit being a full-stack framework, I still decided to adopt a separate front-end and back-end architecture for this blog project. I believe that this separation makes the project cleaner, reduces coupling, and aligns with modern development practices. Furthermore, I wanted to practice developing a purely back-end API.

As for the more detailed development approach, I plan to use Clean Architecture for the overall structure. Of course, such a small project may not necessarily require such complex design patterns, but I want to give myself an opportunity to practice them.

These will allow me to become more proficient in these modern development practices and leave a lot of flexibility and room for adjustments in the future.

For more information about the development process, you can check out the project board. As for the details of the architecture and convention, you can find them in the docs/ directory — start with Project Structure & Architecture, and see the Git Convention for commit and pull request rules.

Build & Development Setup

Prerequisites

  • Bun - Package manager and runtime for frontend
  • Rust - For backend development
  • Podman (Optional) - For containerized deployment

Pre-commit Setup

This project uses pre-commit hooks to ensure code quality. To set up pre-commit:

  1. Install pre-commit:

    pip install pre-commit
    
  2. Install the git hook scripts:

    pre-commit install
    

The pre-commit configuration will automatically run:

  • Backend Rust code checking
  • Frontend linting
  • SQL schema preparation

Backend Setup

For detailed backend development setup, see backend/README.md.

Quick start:

  1. Install sqlx CLI: cargo install sqlx-cli
  2. Run database migrations: sqlx migrate run
  3. Prepare SQL schema: cargo sqlx prepare --workspace
  4. Run the server: RUST_LOG=debug cargo run

Frontend Setup

For detailed frontend development setup, see frontend/README.md.

Quick start:

  1. Navigate to frontend directory: cd frontend
  2. Install dependencies: bun install
  3. Start development server: bun run dev
  4. Build for production: bun run build

Full Project Setup

To set up the entire project:

  1. Clone the repository
  2. Set up pre-commit hooks (see above)
  3. Set up backend (see backend/README.md)
  4. Set up frontend (see frontend/README.md)
  5. Start both servers for full-stack development

Deployment

Self-hosting uses the Kubernetes manifests in manifest/README.md.

CI configuration

Publishing a release runs the Deployment workflow, which builds and pushes the frontend and backend images and attaches a zip of manifest/ to the release. It reads the Actions variables and secrets below, set at the repository or owner level (Settings → Actions).

Variables

Name Example Used for
REGISTRY registry.squidspirit.com Registry host for the login step, build cache and image tags.
REGISTRY_USERNAME squid Registry account for the login step.
IMAGE_REPO_FRONTEND squid/blog-frontend Frontend image name under REGISTRY.
IMAGE_REPO_BACKEND squid/blog-backend Backend image name under REGISTRY.

Secrets

Name Required Used for
REGISTRY_PASSWORD Yes Password or token for REGISTRY_USERNAME.
SENTRY_AUTH_TOKEN No Uploads frontend source maps to Sentry; the frontend still builds without it.

Attaching the manifest to the release uses the GITEA_TOKEN that Gitea provides to every job, so no separate token secret is required.

License

The source code is licensed under the Apache License 2.0. You are free to use, modify, and redistribute the code, including for your own blog.

The project's name and branding ("SquidSpirit" / "魚之魷魂", the logo, and personal content) are not covered by the code license. See TRADEMARK.md for the trademark policy — in short, if you deploy a modified copy, replace the branding with your own.

v0.8.0
Latest
2026-09-24 16:23:29 +08:00
Languages
Rust 39.2%
Svelte 30.7%
TypeScript 27%
CSS 1.1%
JavaScript 0.7%
Other 1.3%