How cja1z/speas works
Project Type and Purpose
• This is a full-stack web application (“PeAS”) built with Deno/TypeScript on the backend, plain HTML/CSS/JS (with Tailwind) for frontend, and PostgreSQL for persistence.
• Purpose: a digital archive system with public and admin UIs, RESTful API, file storage, email notifications, and analytics/logging.
File Structure
• Top-level “Deno/” folder contains both frontend assets (Public/, admin/) and backend code (api/, controllers/, services/, models/, routes/, middleware/).
• Configuration and setup: config/, deps.ts, server.ts, deno.json, .env.
• Database layer: db/ (connection, schema, migrations).
• Storage: local filesystem under “storage/” with subfolders per document type.
• Logging: logs/ (email activity, job logs).
• Utilities & scripts for maintenance and background jobs.
README Insights
• Confirms components: public pages, admin dashboard, API endpoints, user roles, document management workflows, email service, tracking.
• Technology choices: Deno runtime, TypeScript, PostgreSQL, SMTP, PDF metadata extraction.
Main Components & Interactions
a. Frontend UIs
• Public UI: served under “/” – HTML, CSS, JS assets in Deno/Public/
• Admin UI: served under “/admin” – assets in Deno/admin/
b. Backend API Layer
• Routes (Deno/routes/) map HTTP endpoints to controller methods.
• Controllers (Deno/controllers/) orchestrate requests.
• Services (Deno/services/) encapsulate business logic.
• Models (Deno/models/) define ORM-like interaction with PostgreSQL.
• Middleware (Deno/middleware/) handles auth & permission checks.
c. Persistence
• PostgreSQL database (db/schema.sql + migrations). Table models for users, documents, visits, logs, permissions.
• File storage on disk (storage/), organized by document category.
d. Auxiliary Services
• EmailService: sends notifications via SMTP.
• BackgroundJobService: handles asynchronous tasks (e.g., email-logs processing).
• PDFService: extracts metadata from uploaded PDFs.
e. Logging & Analytics
• Application logs (Deno/logs).
• Page visits, document views stored to database via services/controllers.
f. External Dependencies
• SMTP server for email.
• (Optional) CDN or static file server for serving assets.
Architectural Patterns & Principles
• Layered MVC-style architecture:
Presentation (frontend) → API routes → Controllers → Services → Models → Database.
• Separation of concerns: business logic in services; persistence in models; request routing in routes.
• Single monolithic codebase with clear module boundaries.
• RESTful API design.
• Role-based access control via middleware.