How dapbyte/traceon-private works
1. High-level shape
- TraceOn is a native PHP 8.3 MVC application with a MySQL 8+ database and a vanilla JavaScript ES-module frontend.
- It is organized as a single monolith: backend routes, business logic, database access, and server-rendered views live in the same repo.
2. Request entry and routing boundary
- All browser traffic enters through public/index.php behind public/.htaccess, which acts as the front controller.
- URL dispatch is centralized in routes.php and handled by app/Core/Router.php.
- Request/response handling is abstracted by app/Core/Request.php and app/Core/Response.php.
3. Core application services
- app/Core/Database.php provides the PDO/MySQL connection layer.
- app/Core/Session.php manages session state, with session files stored in the sessions/ directory.
- app/Core/CsrfManager.php is the anti-CSRF boundary for mutating requests.
- app/Controllers/BaseController.php likely provides shared controller utilities such as rendering and auth checks.
4. Domain controllers and responsibilities
- The main backend surface is split into focused controllers:
- AuthController: login, register, logout
- WorkspaceController: workspace lifecycle, invite/join flows
- MemberController: workspace membership and roles
- CardController: card management and card access control
- TodoController: todo CRUD and status updates
- ActivityController: activity feed, search/filter/pagination
- ProfileController: user profile and avatar updates
- HealthController: app health/status endpoint
- These controllers are the orchestration layer between HTTP, models, helpers, and views.
5. Persistence and data model
- Database access is encapsulated in **app/Models/*** classes rather than scattered SQL.
- The schema is bootstrapped from migrations/0001_init.sql and extended by 0002_add_priority.sql.
- The domain tables called out in the README are:
- users
- workspaces
- workspace_members
- cards
- card_access
- todos
- activities
- login_attempts
- That structure shows clear boundaries between identity, collaboration/workspace membership, task tracking, and audit logging.
6. Cross-cutting helpers
- app/Helpers/ActivityLogger.php is the shared audit trail writer used when important domain changes happen.
- app/Helpers/ProgressCalculator.php computes card/workspace progress from todo state.
- app/Helpers/FileUploadHelper.php handles avatar upload validation/storage.
- These helpers indicate that progress and auditing are not embedded in the UI; they are backend concerns shared across controllers.
7. Security and access control
- The app uses bcrypt for password hashing, prepared statements via PDO, CSRF tokens, and session regeneration after login.
- Authentication state is session-based, and access is further constrained by:
- workspace roles: Owner / Admin / Member
- card-level access control through card_access
- The presence of login_attempts suggests brute-force tracking or rate-limiting logic around authentication.
8. Server-rendered UI layer
- Views are organized under app/Views/layouts, pages, and partials.
- There are separate layouts for authenticated vs. auth pages:
- layouts/main.php
- layouts/auth.php
- Key pages include dashboard, login, register, profile, and workspace.
- Shared UI fragments like sidebar, toast notifications, and confirmation modal are isolated as partials.
9. Client-side interaction layer
- Frontend behavior is split into ES modules under public/js/modules and page-specific scripts under public/js/pages.
- Modules like api, card, todo, activity, sidebar, modal, and toast suggest the UI makes incremental requests back to the PHP backend rather than doing a full SPA rewrite.
- The frontend is therefore a thin interaction layer over server-rendered pages and JSON-style actions.
10. File and asset handling
- Static assets are served from public/css and public/js.
- User-uploaded avatars live under public/uploads/avatars, with a local .htaccess indicating explicit access control for that directory.
- CSS is structured with tokens, base styles, component styles, and layout styles, which supports a componentized UI but not a separate design system service.
11. Primary data flows
- Authentication flow: browser → AuthController → UserModel / LoginAttemptModel → Session → redirected authenticated views.
- Workspace/card/todo flow: browser action → controller → model updates → progress recalculation → activity log entry → updated dashboard/workspace view.
- Activity flow: controllers write events through ActivityLogger; ActivityController reads/filter/paginates them for display.
- Profile flow: profile form submission → ProfileController → UserModel + FileUploadHelper → updated session-visible profile data.
12. Operational/runtime boundaries
- The app is intended to run on a standard PHP server, with local development via php -S localhost:8000 -t public.
- Composer is used for dependency management, but the architecture is otherwise framework-light and self-contained.
- The meaningful external dependency is the MySQL database; everything else is file-based within the repo or browser-delivered assets.
Main entry points: Router.php Router · main.js Browser modules · main.php Views · AuthController.php Auth
Components 24
Request layer
HTTP entrypoint, routing, and response handling
- Front controller · Main HTTP entry through the public web root
public/index.php - Rewrite rules · Web server rewrite boundary into the front controller
public/.htaccess - Router · Maps routes to controller actions
app/Core/Router.php - Request/Response · Request parsing and response emission
app/Core/Request.php
Domain backend
Controllers, models, helpers, and shared config
- Core services · Database, session, and CSRF boundaries
app/Core/Database.php - Base controller · Shared controller utilities for rendering and auth checks
app/Controllers/BaseController.php - Auth · Login, registration, logout, and auth state
app/Controllers/AuthController.php - Workspace · Workspace lifecycle and invite/join flows
app/Controllers/WorkspaceController.php - Members · Workspace membership and roles
app/Controllers/MemberController.php - Cards · Card management and access control
app/Controllers/CardController.php - Todos · Todo CRUD and status updates
app/Controllers/TodoController.php - Activity · Activity feed, search, filter, and pagination
app/Controllers/ActivityController.php - Profile · Profile updates and avatar handling
app/Controllers/ProfileController.php - Health · App status endpoint
app/Controllers/HealthController.php - Models · Domain models for users, workspaces, cards, todos, membership, activity, and login attempts
app/Models/UserModel.php - Audit helper · Shared activity/event logging
app/Helpers/ActivityLogger.php - Progress helper · Computes progress from todo state
app/Helpers/ProgressCalculator.php - Upload helper · Validates and stores avatar uploads
app/Helpers/FileUploadHelper.php
UI layer
Server-rendered views and browser modules
- Views · Layouts, pages, and shared partials
app/Views/layouts/main.php - Browser modules · Incremental client-side interaction modules
public/js/main.js - Assets · CSS, JavaScript, and uploaded avatars
public/css/base.css
Persistence
Database schema and runtime state
- Schema migrations · Initial schema and later priority extension
migrations/0001_init.sql - MySQL data · Persistent domain tables and login attempt tracking
- Session files · File-backed PHP session storage
sessions/sess_7bblu43bbdoe40hdtih724kefd
Connections 35
- Rewrite rules → Front controller: rewrites to · Web requests are routed into the front controller
- Front controller → Router: dispatches via · Front controller hands off to centralized routing
- Router → Request/Response: creates · Routes operate on request and response objects
- Router → Auth: routes to · Authentication endpoints
- Router → Workspace: routes to · Workspace lifecycle endpoints
- Router → Members: routes to · Membership and role endpoints
- Router → Cards: routes to · Card endpoints
- Router → Todos: routes to · Todo endpoints
- Router → Activity: routes to · Activity endpoints
- Router → Profile: routes to · Profile endpoints
- Router → Health: routes to · Health endpoint
- Auth → Core services: uses · Authentication relies on DB, sessions, and CSRF
- Workspace → Models: uses · Workspace orchestration persists through models
- Members → Models: uses · Membership changes flow through models
- Cards → Models: uses · Card state and access control are model-backed
- Todos → Models: uses · Todo updates are persisted through models
- Activity → Audit helper: reads/writes · Activity feed is written by helpers and read by controller
- Cards → Progress helper: recalculates · Card progress is derived from todo state
- Todos → Progress helper: updates · Todo changes can trigger progress recomputation
- Profile → Upload helper: uploads via · Avatar updates pass through upload validation/storage
- Auth → Session files: stores auth state · Session-backed authentication state
- Core services → MySQL data: connects to · PDO/MySQL persistence boundary
- Schema migrations → MySQL data: bootstraps · Migrations define the database structure
- Models → MySQL data: queries · All domain models persist to the MySQL database
- Views → Browser modules: drives · Rendered pages are enhanced by browser modules
- Browser modules → Auth: calls · Client-side actions invoke backend auth flows
- Browser modules → Cards: calls · Client-side card interactions hit the card controller
- Browser modules → Todos: calls · Client-side todo interactions hit the todo controller
- Browser modules → Activity: calls · Activity UI uses backend activity endpoints
- Assets → Views: styles · CSS assets support the rendered views
- Assets → Browser modules: supports · JavaScript and static assets ship the client layer
- Base controller → Views: renders · Controllers share rendering into layouts and pages
- Auth → Views: renders · Auth views use the auth layout and pages
- Workspace → Views: renders · Workspace and dashboard views are server-rendered
- Profile → Views: renders · Profile view is server-rendered