Rails-8-API-Image-Processing / docs /ARCHITECTURE_V2.md
denise-oneill-inbox-ru's picture
Deploy Rails 8 Blog v1.0.0 from main 9acb6e4 (part 2)
8b229b3 verified
|
Raw History Blame Contribute Delete
4.95 kB
# Production Architecture v2
## Purpose
This document is the release-facing architecture authority for the deployment-v2 branch.
## Topology
```text
Client
|
v
Hugging Face Docker Space
Rails 8.1
Puma
Thruster
Solid Queue
MemoryStore
|
+---- PostgreSQL --------------------> Neon
| application data
| Active Storage metadata
| ActionText metadata
| Solid Queue tables
| audit/security records
|
+---- S3 API ------------------------> Cloudflare R2
| authoritative Active Storage original bytes
|
+---- controlled public mirror -----> Cloudinary Free
eligible public Post ActionText raster derivatives only
```
Hugging Face compute is disposable. Deleting/recreating the container must not destroy canonical application data.
## Database
All Rails environments use PostgreSQL architecture.
Production:
- resolves through `DATABASE_URL`;
- targets Neon;
- must not use SQLite;
- includes application, ActionText, Active Storage, Solid Queue, audit, soft-delete, slideshow, and security-log schema.
Production destructive database operations require explicit human authorization and a verified backup first.
## Background jobs
Production Active Job adapter: Solid Queue.
The queue shares the primary PostgreSQL topology.
Architecture v2 does not require Redis or Sidekiq.
Puma may run Solid Queue through the existing `SOLID_QUEUE_IN_PUMA` runtime toggle/configuration.
## Cache
Rails production cache store is process-local MemoryStore.
This is intentionally non-durable.
Canonical persisted state must never depend on cache survival.
Dynamic Setting values use canonical keys:
`setting:<key>`
Rack::Attack also keeps its throttle counters in an in-memory cache.
## Scheduled publication
Public visibility is due-aware in the application query contract.
A scheduled Post that has become due can become publicly visible even if a sleeping disposable runtime did not execute a job at the exact scheduled second.
Future/draft/discarded records remain non-public.
## Active Storage originals
Production service: `cloudflare_r2`.
Required variables:
- `R2_ENDPOINT`
- `R2_ACCESS_KEY_ID`
- `R2_SECRET_ACCESS_KEY`
- `R2_BUCKET`
- `R2_REGION`
R2 owns authoritative original media bytes.
Rails/Neon owns Active Storage metadata and references.
## D7 Cloudinary ActionText delivery
Cloudinary Free is a derived delivery layer, not original storage authority.
Only eligible JPEG/PNG/WebP/GIF attachments belonging to a currently publicly-visible Post ActionText field may be mirrored.
Security boundaries include:
- no caller-controlled remote URL;
- exact R2 source-presign contract;
- bounded presign lifetime;
- authenticated Cloudinary asset type;
- fixed eager derivative registry;
- no secret/presign logging or persistence;
- visibility recheck before provider write;
- non-public/stale/unsupported input fails closed.
R2 originals must never be deleted because a Cloudinary mirror is created or removed.
## Slideshow
`Slide` belongs to `Post`.
- image: Active Storage/R2;
- canonical order: persisted `position`;
- localized caption/alt text: `SlideTranslation` via Mobility;
- maximum count: dynamic Setting;
- public/API exposure follows Post public visibility;
- slideshow images are outside the D7 Cloudinary ActionText mirror.
## Authentication and authorization
- Devise for web authentication.
- devise-jwt for API authentication.
- Pundit for authorization.
- Roles: admin, author, reader.
- Admin namespace remains admin-only.
## Audit and soft deletion
- PaperTrail stores audited changes.
- Post/Comment use Discard for soft deletion.
- Admin trash/restore flows are audited.
- Discarded Posts are excluded from public visibility.
## Security throttling/logging
Rack::Attack:
- throttles POST login attempts only;
- reads dynamic limits from Setting;
- uses Setting-backed blocked/whitelisted IP lists;
- returns bounded JSON failure responses.
`BlockedRequestLog`:
- bounds path/user-agent byte length;
- preserves valid UTF-8;
- retains only the newest configured maximum rows.
## Deployment boundary
The target Docker runtime must:
- boot Rails in production;
- listen through the configured port;
- authorize the expected Hugging Face host;
- resolve PostgreSQL, R2, Solid Queue and MemoryStore production contracts;
- remain safe across container restart because persistent state is external.
## Invariants that must remain true
1. no SQLite production adapter;
2. no Redis/Sidekiq production dependency;
3. Neon/PostgreSQL owns relational durability;
4. R2 owns original media durability;
5. Cloudinary is derived public ActionText delivery only;
6. slideshow stays on Active Storage/R2;
7. Hugging Face disk is disposable;
8. non-public content/media does not leak through public API/rendering;
9. accepted coverage floors do not regress;
10. push/tag/release actions remain human-authorized.