Files
squid 119d900cdf NO-ISSUE Refactor for better clean architecture (#326)
### Description

- Rename the backend application layer `gateway` to `port`, and `common` to `shared`, to match the Clean Architecture vocabulary used across the project.
- Split backend infrastructure interfaces (`adapter/port`) from their implementations and DTOs (`adapter/gateway`).
- Rename db mappers to db models and split `CreatePostDbModel` / `UpdatePostDbModel` to simplify post writes.
- Rename database tables and schema objects (tables, triggers, indexes, sequences, constraints) to plural via new `sqlx migrate` migrations. Earlier migrations are left untouched.
- Rename the frontend `common` layer to `shared` and adopt `domain/application/adapter/framework` per feature.
- Split `container.ts` into per-feature composition roots.
- Add a shared HTTP client (`ApiClient`) for frontend API services.
- Extract shared presenter primitives: `AsyncState`, `ActionStore` and `BaseActionStore`.
- Move form validation into the application layer.
- Guard dashboard routes on the server.
- Make post draft creation explicit.
- Move all frontend UI strings into `Strings` and constant URLs into `links`.
- Rename the workspace crate `common` to `shared`; no external dependency versions changed.
- Deployment note: run the rename migrations before deploying the new backend code.

### Package Changes

None

### Screenshots

None

### Reference

None

### Checklist

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

Reviewed-on: #326
Co-authored-by: SquidSpirit <squid@squidspirit.com>
2026-11-03 16:45:00 +08:00
..

Frontend

Development

Prerequisites

  • Bun - Package manager and runtime

Setup

  1. Install dependencies:

    bun install
    
  2. Start development server:

    bun run dev
    
  3. Build for production:

    bun run build
    
  4. Preview production build:

    bun run preview
    

Development Commands

  • Type checking: bun run --bun check
  • Type checking (watch mode): bun run --bun check:watch
  • Linting: bun run --bun lint
  • Formatting: bun run format

Mock API

To check layouts without running the backend, start the dev server with the mock API enabled:

PUBLIC_USE_MOCK_API=true bun run dev

The fixtures live in src/lib/shared/framework/mock/ and serve fake posts, labels, and a logged-out /me, so /post, /post/[id], and the search dialog all render. The mock is only wired up in dev mode and stays inert unless PUBLIC_USE_MOCK_API=true.

Project Structure

The frontend is built with SvelteKit and Tailwind CSS following Clean Architecture principles:

  • src/lib/shared/ - Cross-feature building blocks (HTTP, presenters, shared UI)
  • src/lib/<feature>/ - Feature modules such as post, label, image, and auth
  • src/routes/ - SvelteKit route pages
  • src/app.html - Main HTML template
  • src/app.css - Global styles

Each feature module in src/lib/ follows the Clean Architecture pattern:

  • domain/ - Business logic and entities
  • application/ - Use cases and application ports (port/)
  • adapter/ - Interface adapters
    • port/ - External service interfaces such as API clients
    • gateway/ - Implementations of application ports and dto/ transfer objects
    • presenter/ - Stores (store/) and view models (viewModel/)
  • framework/ - External frameworks (API implementations, UI components)
  • composition.ts - Wires the feature's API service, repository, use cases, and stores

src/lib/container.ts aggregates the feature composition modules. Components access it through getContainer() from src/lib/shared/framework/ui/containerContext.ts.

Technology Stack

  • Framework: SvelteKit 5
  • Styling: Tailwind CSS 4
  • UI Components: bits-ui, Lucide icons
  • Type Safety: TypeScript
  • Linting: ESLint with Prettier
  • Package Manager: bun

Sitemap & Feed

The frontend serves its own discovery documents, so the public URL scheme is defined only here:

  • /sitemap.xml - every published post plus the static pages the backend cannot know about (home, post list, terms).
  • /feed.xml - an RSS 2.0 feed of the 20 most recent posts. Items are identified by the post's semantic id, so their guid stays stable when URLs change.

Both are generated on demand from src/lib/seo/ and served with Cache-Control: public, max-age=300, so a newly published post shows up without a rebuild or a separate generation step.