File size: 4,945 Bytes
8b229b3 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 | # 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.
|