# cja1z/speas architecture

> Architecture diagram of the GitHub repository cja1z/speas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cja1z/speas
- Repository: https://github.com/cja1z/speas

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        PublicUI["Public UI"]:::frontend
        AdminUI["Admin UI"]:::frontend
    end

    %% Backend Monolith
    subgraph "Backend Monolith"
        Server["HTTP Server<br/>(server.ts)"]:::backend
        Deps["Dependency Definitions (deps.ts)"]:::backend
        Config["Configuration<br/>(config/)"]:::backend
        subgraph "Routes & Middleware"
            Routes["API Routes"]:::backend
            AuthMW["Auth Middleware"]:::backend
            PermMW["Permission Middleware"]:::backend
        end
        subgraph "Controllers & Services"
            Controllers["Controllers"]:::backend
            subgraph "Services"
                AuthSvc["AuthService"]:::backend
                SessSvc["SessionService"]:::backend
                DocSvc["DocumentService"]:::backend
                UploadSvc["UploadService"]:::backend
                FileChkSvc["FileCheckService"]:::backend
                EmailSvc["EmailService"]:::backend
                JobSvc["BackgroundJobService"]:::backend
                PDFSvc["PDFService"]:::backend
                PermSvc["PermissionsService"]:::backend
                CatSvc["CategoryService"]:::backend
                UserSvc["UserService"]:::backend
            end
        end
        Models["Models"]:::backend
        Utils["Utilities & Scripts"]:::utils
        subgraph "Scripts & Maintenance"
            Scripts["Scripts"]:::utils
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["PostgreSQL DB"]:::data
        Storage["File Storage"]:::data
        Logs["Logs Directory"]:::data
    end

    %% External Services
    subgraph "External Services"
        SMTP["SMTP Email Service"]:::external
    end

    %% Background Jobs
    subgraph "Background Jobs"
        JobQueue["Job Queue/Scheduler"]:::backend
    end

    %% Connections
    PublicUI -->|HTTP| Server
    AdminUI -->|HTTP| Server

    Server -->|uses| Deps
    Server -->|loads| Config
    Server -->|routes to| Routes

    Routes -->|auth check| AuthMW
    Routes -->|permission check| PermMW
    AuthMW -->|to controllers| Controllers
    PermMW -->|to controllers| Controllers

    Controllers -->|invoke| AuthSvc
    Controllers -->|invoke| SessSvc
    Controllers -->|invoke| DocSvc
    Controllers -->|invoke| UploadSvc
    Controllers -->|invoke| FileChkSvc
    Controllers -->|invoke| EmailSvc
    Controllers -->|invoke| PDFSvc
    Controllers -->|invoke| PermSvc
    Controllers -->|invoke| CatSvc
    Controllers -->|invoke| UserSvc
    Controllers -->|access| Models

    AuthSvc -->|reads/writes| Models
    SessSvc -->|reads/writes| Models
    DocSvc -->|reads/writes| Models
    UploadSvc -->|writes| Storage
    FileChkSvc -->|reads| Storage
    EmailSvc -->|sends via| SMTP
    JobSvc -->|processes logs| Logs
    JobSvc -->|schedules via| JobQueue
    PDFSvc -->|extracts from| Storage
    PermSvc -->|reads/writes| Models
    CatSvc -->|reads/writes| Models
    UserSvc -->|reads/writes| Models

    Models -->|SQL queries| DB

    %% Click Events
    click PublicUI "https://github.com/cja1z/speas/tree/peas-main/Deno/Public/"
    click AdminUI "https://github.com/cja1z/speas/tree/peas-main/Deno/admin/"
    click Server "https://github.com/cja1z/speas/blob/peas-main/Deno/server.ts"
    click Deps "https://github.com/cja1z/speas/blob/peas-main/Deno/deps.ts"
    click Config "https://github.com/cja1z/speas/blob/peas-main/Deno/config/config.ts"
    click Config "https://github.com/cja1z/speas/blob/peas-main/Deno/config/env.ts"
    click Config "https://github.com/cja1z/speas/blob/peas-main/Deno/config/db.ts"
    click Routes "https://github.com/cja1z/speas/tree/peas-main/Deno/routes/"
    click Controllers "https://github.com/cja1z/speas/tree/peas-main/Deno/controllers/"
    click AuthSvc "https://github.com/cja1z/speas/blob/peas-main/Deno/services/authService.ts"
    click SessSvc "https://github.com/cja1z/speas/blob/peas-main/Deno/services/sessionService.ts"
    click DocSvc "https://github.com/cja1z/speas/blob/peas-main/Deno/services/documentService.ts"
    click UploadSvc "https://github.com/cja1z/speas/blob/peas-main/Deno/services/uploadService.ts"
    click FileChkSvc "https://github.com/cja1z/speas/blob/peas-main/Deno/services/fileCheckService.ts"
    click EmailSvc "https://github.com/cja1z/speas/blob/peas-main/Deno/services/emailService.ts"
    click JobSvc "https://github.com/cja1z/speas/blob/peas-main/Deno/services/backgroundJobService.ts"
    click PDFSvc "https://github.com/cja1z/speas/blob/peas-main/Deno/services/pdfService.ts"
    click PermSvc "https://github.com/cja1z/speas/blob/peas-main/Deno/services/permissionsService.ts"
    click CatSvc "https://github.com/cja1z/speas/blob/peas-main/Deno/services/categoryService.ts"
    click UserSvc "https://github.com/cja1z/speas/blob/peas-main/Deno/services/userService.ts"
    click Models "https://github.com/cja1z/speas/tree/peas-main/Deno/models/"
    click AuthMW "https://github.com/cja1z/speas/blob/peas-main/Deno/middleware/authMiddleware.ts"
    click PermMW "https://github.com/cja1z/speas/blob/peas-main/Deno/middleware/permissionMiddleware.ts"
    click DB "https://github.com/cja1z/speas/blob/peas-main/Deno/db/database.ts"
    click DB "https://github.com/cja1z/speas/blob/peas-main/Deno/db/denopost_conn.ts"
    click DB "https://github.com/cja1z/speas/blob/peas-main/Deno/db/schema.sql"
    click DB "https://github.com/cja1z/speas/tree/peas-main/Deno/db/migrations/"
    click Storage "https://github.com/cja1z/speas/tree/peas-main/storage/"
    click Logs "https://github.com/cja1z/speas/tree/peas-main/Deno/logs/"
    click Scripts "https://github.com/cja1z/speas/tree/peas-main/Deno/scripts/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef data fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef utils fill:#D3D3D3,stroke:#000,stroke-width:1px
```
