mirror of
https://github.com/Dvorinka/Primora.git
synced 2026-07-29 06:53:48 +00:00
253 lines
3.8 KiB
Markdown
253 lines
3.8 KiB
Markdown
# PRIMORA — Backend Platform OS (System Design Spec)
|
|
|
|
A self-hosted developer platform inspired by Appwrite-style UX, built for:
|
|
- speed
|
|
- clarity
|
|
- composability
|
|
- low resource usage
|
|
- full backend ownership
|
|
|
|
---
|
|
|
|
# 🧠 Core Philosophy
|
|
|
|
Primora is not a BaaS.
|
|
|
|
It is a:
|
|
|
|
> **Backend Operating System for building products**
|
|
|
|
Everything is explicit. Nothing is hidden.
|
|
|
|
---
|
|
|
|
# ⚙️ System Principles
|
|
|
|
- No vendor lock-in
|
|
- No managed backend services
|
|
- Full control over auth, DB, storage, API
|
|
- Minimal runtime overhead
|
|
- Local-first / self-host-first architecture
|
|
- Predictable performance under load
|
|
|
|
---
|
|
|
|
# 🧱 High-Level Architecture
|
|
|
|
|
|
Frontend (SolidJS / React)
|
|
↓
|
|
Go Backend (Gin API Layer)
|
|
↓
|
|
PostgreSQL + DragonflyDB
|
|
↓
|
|
Local File System Buckets
|
|
|
|
|
|
---
|
|
|
|
# 🧩 Core System Modules
|
|
|
|
## 1. Auth System
|
|
- Custom JWT OR Better Auth integration layer
|
|
- Session validation handled in Go
|
|
- Token-based API access
|
|
|
|
Rules:
|
|
- Backend owns auth enforcement
|
|
- No external auth dependency
|
|
- All roles & permissions stored in Postgres
|
|
|
|
---
|
|
|
|
## 2. API Layer (Go)
|
|
|
|
Stack:
|
|
- Gin (HTTP server)
|
|
- OpenAPI spec generation
|
|
- REST-first design
|
|
|
|
Responsibilities:
|
|
- routing
|
|
- validation
|
|
- auth enforcement
|
|
- business logic execution
|
|
|
|
---
|
|
|
|
## 3. Database Layer
|
|
|
|
PostgreSQL is the single source of truth.
|
|
|
|
Tools:
|
|
- sqlc (type-safe queries)
|
|
- goose (migrations)
|
|
|
|
Rules:
|
|
- No ORM abstraction layers
|
|
- No dynamic schema generation
|
|
- Explicit schema evolution only
|
|
|
|
---
|
|
|
|
## 4. Cache Layer
|
|
|
|
DragonflyDB used for:
|
|
- session caching
|
|
- rate limiting
|
|
- hot API responses
|
|
- temporary state
|
|
|
|
NOT used for:
|
|
- persistent storage
|
|
- critical business data
|
|
|
|
---
|
|
|
|
## 5. File Storage System
|
|
|
|
Local filesystem-based bucket system:
|
|
|
|
|
|
/data
|
|
/bucket_users
|
|
/bucket_projects
|
|
/bucket_assets
|
|
|
|
|
|
Features:
|
|
- streaming uploads (no full memory load)
|
|
- chunked writes
|
|
- metadata stored in Postgres
|
|
- fast local reads
|
|
- no external S3 dependency
|
|
|
|
---
|
|
|
|
## 6. OpenAPI System
|
|
|
|
- Go generates OpenAPI spec
|
|
- Frontend auto-consumes API contracts
|
|
- Optional SDK generation for:
|
|
- TypeScript
|
|
- Python
|
|
- Rust
|
|
- Java
|
|
|
|
---
|
|
|
|
# 🖥️ Frontend System
|
|
|
|
## Default Stack
|
|
|
|
- SolidJS (primary)
|
|
- React (fallback only when required)
|
|
|
|
---
|
|
|
|
## Required Tooling
|
|
|
|
- Vite
|
|
- TypeScript (strict mode)
|
|
- Tailwind CSS
|
|
|
|
---
|
|
|
|
## UI Libraries
|
|
|
|
- Ark UI (Solid)
|
|
- shadcn / shadcn-solid
|
|
|
|
---
|
|
|
|
## UI Requirements
|
|
|
|
- Fully responsive
|
|
- Dark / light mode support
|
|
- Accessibility-first design (ARIA compliant)
|
|
- Keyboard navigation support
|
|
|
|
---
|
|
|
|
# 🎨 UI Design Principles
|
|
|
|
- Dark-first interface
|
|
- Dense but breathable layout
|
|
- Card-based system
|
|
- Clear hierarchy via contrast
|
|
- Minimal animation usage
|
|
- Blue accent system (`#19a3d9`)
|
|
|
|
---
|
|
|
|
# ⚡ Performance Targets
|
|
|
|
- API latency: < 50ms local
|
|
- UI render: < 100ms interaction response
|
|
- Go backend memory: low footprint (<150MB typical)
|
|
- Idle CPU: near zero
|
|
- File streaming: zero-copy when possible
|
|
|
|
---
|
|
|
|
# 🧱 Backend Ownership Rules
|
|
|
|
Backend owns:
|
|
|
|
- authentication
|
|
- authorization
|
|
- API logic
|
|
- database access
|
|
- business rules
|
|
|
|
Frontend NEVER:
|
|
- validates security logic
|
|
- enforces permissions
|
|
- directly accesses DB
|
|
|
|
---
|
|
|
|
# 🚀 Deployment Model
|
|
|
|
Primary target:
|
|
- Railway
|
|
- single container deploy
|
|
- optional volume for file storage
|
|
|
|
Constraints:
|
|
- minimal service count
|
|
- no microservice sprawl
|
|
- no external dependencies required
|
|
|
|
---
|
|
|
|
# 🧠 Scalability Model
|
|
|
|
Primora scales by:
|
|
|
|
- stateless Go API layer
|
|
- Postgres indexing + optimization
|
|
- Dragonfly caching layer
|
|
- optional horizontal API scaling
|
|
|
|
File system scales via:
|
|
- disk expansion
|
|
- optional migration layer later
|
|
|
|
---
|
|
|
|
# 🧩 Summary
|
|
|
|
Primora is:
|
|
|
|
> A fully self-owned backend operating system combining Go, Postgres, and a modern frontend layer, designed for clarity, speed, and full control.
|
|
|
|
It avoids:
|
|
- BaaS lock-in
|
|
- hidden abstractions
|
|
- unnecessary distributed complexity
|
|
|
|
It prioritizes:
|
|
- explicit systems
|
|
- predictable behavior
|
|
- developer control |