
= The Talkyard World



== Different types of "Posts"

In Talkyard, pages and replies are "posts":

**Update 2023:** Pages, comments, categories, flags `[flags_as_posts]`
will eventually all be in a single nodes_t table.
Turns out they share almost everything, and keeping
them in separate tables results in duplicated fields & code. **/Update**

Forum Post = new forum discussion page, a.k.a. thread, or Original Post.
Forum Reply = A reply to a forum post.

Forum intro post = Shown at the top of the forum post index page
and explains what the forum is about. Can be collapsed.

Blog Post = blog article.
Blog Comment = a reply to a blog article.

Wiki Page = a wiki page.
Wiki Comment = a comment on a wiki page.


== Different types of pages

Index pages a.k.a. site section pages: Currently only of type Forum,
to list forum topics. Later, maybe Wiki main pages too, or Blog post index pages.

Description pages: Meta pages that describes categories and tags and their purposes.

Topic pages: The actual contents in the community. E.g. ideas, questions,
open-ended discussions. Or articles or documentation. — The things end users
visit the community for.

Other pages, e.g. flag pages — for reporting a post.

Index pages and description pages are just there to help the end users
find the actual topic pages.

Source code wise, each page has a `PageType` field with values like
Forum or Blog — if it's an index page. Or Question, Idea, Discussion etc
— if it's a (discussion) topic page.


=== Index pages

(A.k.a. site section pages.)
There's just one index page type, currently, namely forum topi list pages.
Later there'll be a Wiki section page type too? Or even a Blog
section page type but probably static HTML blogs are better — or Ty could
have an API for exporting a blog section page to static HTML or CommonMark,
then discussing via embedded comments. Similar to exporting from, say,
WordPress to static HTML.

Maybe optional per user feed page(s) in the future.


=== Description pages

When in a forum category, click Edit Category, then Edit Description
to see the category description page.

Or about user texts (bios), or tag descriptions.


=== Topic pages

E.g. questions, ideas, problems, discussions, documentation articles.

Questions can be answered / solved.

Ideas and Problems can be solved too: a reply selected as
e.g. a problem solution.  `[tpc_typ_solv]`
Or they can have their doing status
toggled from discussing (triage) to planned, doing, done — without any particular
reply selected as a solution.

There're three kinds of topic types: Outside-In, Inside-Out, and Discussions:

==== Outside-In

Pepole outside the organization make feature requests, report problems,
post questions to the organization and each other. These types:

- Questions: How do I do this?
- Problems (bug reports): This seems broken, can you fix?
- Ideas, e.g. feature requests.

(If you use Ty for internal support, the ones posting Outside-In
topics would be your co-workers, not customers.)

==== Inside-Out

The organization writes something, and publishes for their
audience to read. E.g. a company publishes a blog article, or help docs,
or an announcement, for their customers and users to read. These types:

- Announcements (for existing customers about new features)
- Documentation (for existing customers about how to use already existing features)
- Articles (e.g. blog articles for attracting new customers)

==== Discussions

People both in and outside the organization discuss something. These types:

- Discussion: open-ended discussion, typically there's no single best answer.
- Embedded comments, e.g. discussing a blog posts.
- Link pages: For just posting a link and discussing it, like at Reddit or HackerNews.
  Slightly makes Talkyard work like a news aggregator.

=== Flag Pages and Posts

In Ty, flags (e.g. someone reporting a comment) will "soon" be stored as
posts of PostType.Flag `[flags_as_posts]`,
and linked to the things they flag, via `post_rels_t`. So, one flag can flag
many things at once — say, comments claiming that 5G towers spread covid virus,
then, could be nice to report all those posts at once (rather than one flag for each).
Also less work for mods to handle.
Or, astroturfing, then one would want to report an astroturfer's all 999 possible
accounts at the same time, rather than individually 999 times?

When each flag is its own post of PostType.Flag on a page of PageType.Flag, then,
staff can reply to the flagger and ask hen to clarify,
if anyhting is unclear. And staff can post private comments on the flag page,
and have a staff-only discussion about the flag.

The links to flagged things are form the flag post, not the person — because
the same person might flag the same thing many times (say, a text that gets edited).
A new post gets a new id and can work as the new id for a new flag of the same thing.
(But a person's id stays the same.)




== Anonyms and Pseudonyms

Also see: ../wip/aliases/wip.txt. This section here in tyworld.adoc is out-of-date!

=== Anonyms posts

When you anonymously, then, a new anonym (anonymous user) is created, for you,
to use in the current discussion, on that specific page. You can't use it outside that page
(instead, another then gets created).  Anon comments cannot be moved to
other pages, and aren't visible to others (only to yourself) in the activity
list on your user profile page, or in your posts counts. [list_anon_posts]

Currently, you can have only one anonym persona per page [one_anon_per_page].
(Actually, you can have more, if someone moves the page between categories that use
different types of anonyms (temporary anonyms or permanent anonyms), and you post
anonymous comments of each type. In such cases, you can have one anonym
per page and anonym type (`AnonStatus`))  It'd be confusing if people could create many
anonymous users and pretend to be many people, in a single discussion.

The software remembers if you want to be anonymous or not, per
discussion page, by looking at your previous comments in that discussion
and sub thread you're replying in — because maybe you're using using your
real account, in one sub thread, but replying anonymously in another
(on the same page).

So, you're unlikely to accidentally post using the wrong anonymous account
since the software does the right thing automatically.

=== Anonymous votes

If you've commented anonymously on a page, or the page is anon-by default,
then, your votes on that page are anon by default, too
(using the same anon account).

[anon_votes]

=== Anonymous categories

Categories can be 1) always-anonymous, or 2) anon by default, or
3) real account by default but anon posts allowed. Or 4) anon posts
not allowed (only real accounts). Edit: See `[NeverAlways]`.

Not implemented: If, when enabling anonymity in a category, the admin selects
_Better ideas & decisions_ as the purpose (but not _Sensitive Discussions_), then,
the category can be configured to get _de-anonymized_ after a while (!).
For example, two weeks after a new page has been posted in that category,
the real usernames get shown so everyone can see who wrote what.
In such categories, before posting, there's an obtrusive info box about this,
so everyone will know how it works.

=== For the workplace

Anonymous categories and de-anonymizing be helpful in the workplace: Posts can
start anonymous, for better decision making (when people judge an idea more for
what it is, not knowing if it's from a new hire, a friend, their boss or the CEO).

And the posts can get deanonymized after some weeks,
when the discussion has ended — so people can get recognized, eventually,
for good ideas they had. (Optionally only posts that got some Like-votes.)

=== Pseudonyms

Pseudonyms (not implemented `[pseudonyms_later]`) will work differently:

You can have only a few pseudonym account, and you switch to one of them,
and use it, until you switch back to your real user account.
Not so different from signing up using different email addresses
— however, you don't need to create lots of email addresses and sign up
many times and log in and out "all the time". Instead, you just click your
username menu, and choose "Switch to pseudonym".

And you get to see notifications for all your pseudonyms, at once
(and if you click one, the software suggests that you switch to the related
pseudonym, if you want to reply).

A pseudonym of yours, can have a different reputation (= trust? knowledge? level)
than your main account. Consider a large community, with sub communities and
moderators. If you use a pseudonym in one sub community, and the people there
are unreasonably happy or angry with what your pseudonym writes, and upvotes
your pseudonym's comments surprisingly often or infrequently — then, your pseudonym
could get a different reputation than your main account. Although you're
the same person.  `[pseudonyms_trust]`

Possibly, there'll be different types of pseudonyms. See
../wip/aliases/wip.txt [pseudonym_types].

=== Tech notes

Not impl, and this'll change:
Implementation wise, to show notifications from all one's pseudonyms,
Talkyard does one lookup per pseudonym. So that's why you cannot
have hundereds of pseudonyms (because then this'd be slow).
But one's anon comments point directly to your real account, only the
`author_id_c` field points to the anonym. Then it's just one lookup,
to list all one's anon posts. Hence, no need to restrict how many anon users
one can have.

Anon posts are implemented by assigning authorship to your anonym user account,
for the page in question. But your main account remains the owner, and keeps
getting notified of replies.




== Post Owners and Authors

(Not implemented.)

You can assign authorship of a post to someone else.
Then, that person's (or people's, or group's) name is shown as the author,
and no one sees you originally wrote that post.
When doing this, you get to choose if you still want to get notified of replies or not.

You can also assign ownership of a post of yours, to someone else.
Thereafter, you cannot edit or delete or do anything with the post — it's as
if that other person had posted it, originally.
When doing this, you get to choose if you want to keep getting notified of replies.

But when assigning authorship or ownership to someone else,
then, for this to take effect, first that other person needs to agree:
hen gets a notification, and gets to click a Yes or No button,
and gets to choose if hen wants to start getting notified of replies
(by default, yes).




== Forum post statuses




== Vote types


All vote types enabled by default, but Disagree can be disabled  [tyworld_5mj98267]
— some people wanted to not have any Disagree votes, but they were
ok with the other votes — just the Like vote, plus Bury and Unwanted for staff,
and optionally Do-It and Do-Not votes.

=== Do-It votes, Do-Not votes and Like votes

Admins can enable Do-It and, optionally, Do-Not votes of topics,
in categories of their choice.
And, optionally, let people do-it(-not) vote directly from the topic list page.

This can 1) make Talkyard work like a news aggregator with vote buttons that
moves a news topic up, or down. (Do and Do-Not then means
"do show this higher up in the news items list" or "do not show higher up").
And can 2) make Ty work like an idea voting tool,
where you can see the number of votes, and also vote,
directly from the question or feature ideas lists — A Do-It vote then means
"Yes, do implement this idea".

These votes are called Do-it (and Do-Not) votes, instead of "upvotes",
because "upvote" would be ambigious — could also refer to a Like vote.

==== Do-It votes and Like votes

Do-It votes and Like votes, can work independenttly of each other,
if the admins want. (Not yet implemented.)
For example, you can Do-Not vote on an idea, and at the same time
Like vote the _description_ of the idea
— in case you like the way the idea was presented,
although you might think it's too off-topic (so you Do-Not voted it).

Maybe this can make a Talkyard communtiy feel extra friendly, when although
someone's idea got Do-Not votes and won't happen, there might still be some
Like votes of the _description_ of the idea, making the idea submitter feel
welcomend although the idea got rejected.

But if Do-It votes and Like votes were the same, it wouldn't be possible to
both Do-Not and Like vote a topic (because that'd mean Do-Not and yes-Do-It
votes at the same time by the same person).

Also, maybe in the future maybe each person would get a certain number of Do-It
votes to distribute among all ideas, and hen could add many votes to the
same idea. — Everyone got, say, 10, Do-It votes to distribute among all ieas /
feature requests.
And you could add, say, 3 Do-It votes to a feature that was really important
to you. For this to work, it makes sense to keep Like votes and Do-It votes separate.
(Ty would then show both how many Do-It votes an idea got, _and_ from how many
different people.) — This not implemented.

=== Upvotes and Downvotes

There isn't any single specific "upvote" or "downvote" in Talkyard.

You might say that Do-It and, optionally, Do-Not votes are upvotes and downvotes.
They don't affect people's karma — they're only for indicating how the community
wants to prioritize things.

Or you might say that Like votes and Unwanted votes are upvotes and downvotes.
They affect the post author's karma.

Disagree and Bury votes are not meant as downvotes. Disagreeing isn't
inherently negative, and a Bury voted reply might just be a welcomed "Thanks" or "Me too"
that the staff wanted to move downwards (curating the discussion).
— In fact, something people disagree a bit about, can be more interesting,
than something everyone agrees about? [tywd_disagree_fine]


== Site Sections and Category Trees

[subcoms_and_cats]

A single Talkyard site can have different site sections, a.k.a. sub communities.
E.g. a forum, another forum, a blog, a wiki.
A bit like there's subreddits / sub communities, over at Reddit.

Not yet, but in the future, there will be category specific moderators. Then
it'll be possible to assign some people to moderate a site section (or parts of it).

A site section consists of 1) a category tree, consisting of a root category, and its
descendant categories (child cats, grandchild cats and so on);
and 2) all pages in those categories.
(A page can be in exactly one category, or no category (e.g. private messages).)

A site section root category is called the **tree root** category, whilst
sub tree roots are called **sub root**. "Root category" can refer to both a tree root,
or a sub root.

Children of a tree root are called **base categories** (they're at depth 1 in the tree),
Grandchilds are called "sub categories" (tree depth 2).
Currently (Aug 2022) sub sub categories aren't supported.



== Categories and permissions


=== Sub category permissions

If moving a publicly visible category S to another category B, so that S becomes
a sub category of B, then, in Talkyard, category S won't be any more visible than B.
Anything else would be unexpected: People (incl I) assume that if base category B
is access restricted, then sub cats in B, are, they too.  `[see_sub_cat]`

(Later, maybe maybe there could be a "power admin" feature to optionally allow access
to sub categories, although the base category is access restricted. [power_admin]
Let's say an organizaiton creates a category for a project, and invites external
collaborators to post questions and ideas in a sub category — but the org people
don't want the external people to see the base category.  But the people in the org
still think it's nice to have everything-related-to-the-project in the same category.
Or maybe this'd be better implemented as sub sub cats?
Proj Base Cat: { Proj Private: ...Private sub-sub cats, Proj Ext: ...pub sub-sub cats })

Only may-Not-see is inherited in the category tree — other cat perms, e.g.
may-post-topics, are not inherited; instead, are configured per category.
Maybe it'd be nice if may-edit-wiki permissions got inherited?  Or if, when adding
a sub category, or editing the base category perms, one could apply the base
category settings to the sub cats  `[propagate_cat_perms]`  (instead of inheriting).




== Embedded comments

A Talkyard discussion can be embedded below a blog post, as a blog comments section.
And on other types of web pages, for discussing other things.

There can be many comments iframes, on the same embedding page.
So, for example, a page showing different items in a shop, on the same page,
can have small comment sections about each item, below the item,
simultaneously on the same page, e.g. to show the most popular customer comments
about each item. Could be combined with a button to expand the comments or
maybe go to a full screen discussion page about that item.

Session ID management gets a bit involved in iframes, because cookies generally
don't work — see section Session IDs in ty-security.adoc.

=== Lazy pages

[emb_lzy_pgs]
Each iframe with comments, is backed by a Talkyard discussion page of
type PageType.EmbeddedComments. Such a Talkyard page isn't created
before it's needed — that is, when the first comment gets posted,
or someone clicks Like (then, the like vote needs a page id),
or the blog visitor configures a notify-me-of-comments notification level
for that blog post discussion.

// first comment gets posted (or like vote or notf setting changed).
// So, a draft for the very first comment, usually won't have any page id.)


== Graph theory

In a way, Ty uses PostgreSQL as a `[graph_database]`, with nodes being rows in
tables that store people, pages, comments, categories, tags, notifications,
permissions, etc.

And edges are stored in `post_rels_t` and `pat_rels_t` ("rel" is for
"relationship", as in nodes and relationships, graph terminology).

The eges in the `...rels_t` tables consist of just a start, an end,
a type, and (optionally) a single integer value.

More complicated edges get their own relationship tables. E.g. `perms_on_pats_t`
which can be seen as graph edges from [users or groups] to groups (e.g. group
member or manager)  — but these edges have so many properties, so they're
in their own table, not in `pat_rels_t`.

Generally, Postgres tables _with_ an id primary key would be _nodes_ in a graph.
Whilst tables that _lack_ its own id primary key, would be edges. In Ty, edges don't
need their own ids; instead, they use the primary keys of the start and
end node, and the relationship type, as primary key.

Postgres as a semi graph database, seems nice: Postgres makes it easy
to add indexes and extra unique keys, foreign keys as needed, and custom
datatypes and check constraints. And Postgres is stable & relatively bug free,
open source (not just open core), and has been around for decades —
which cannot be said about any graph database?

And Postgres can `[cluster_tables]`, which makes it possible to fetch
all edges by fetching fewer table blocks from disk (by clustering
on edge start or endpoint as appropriate).



== Custom types and values

Custom types, e.g. tag types, user badge types, are stored in types_t
(currently named tagtypes_t). For example, a tag has a tag type that
says how the tag should be displayed: title, color, descr,
if the tag can have values and then of what type.

A type has a kind id, type id and sub type id.  Once a type has been
created, these never changes. (Is primary key.)

The "kind" says what kind of thing the type is for: nodes (in nodes_t,
currently named posts3), or participants (pats_t, currently users3),
or tags or badges (both stored in tags_t), pat-node relationships,
e.g. Voted-On (a post) or Assigned-To, node-node relationships,
e.g. Depends-On. (And what more?)

Some types have sub types. E.g. nodes of type Page or Flag can
have sub types: PageType.Idea, Question, etc, and FlagType.Inapt, Spam etc.

Other types don't currently need sub types, e.g. tags and badges.

So, a type is:  { kindId, typeId, subTypeId, ... name, descr etc ... }.

Built-in types, though, aren't stored in types_t. (E.g. PageType,
FlagType.)  Currently only tags & badges use types_t (there are no built-in
tag or badge types).

To do?: See `[Custom_types] [Alt_5]`
in ../appsv/rdb/src/main/resources/db/migration/db-wip.sql


=== Tags with values

Tags can have values, e.g. "Version: v1.23.4" or "Event-Location: Paris"
or "Published-Year: 1999". This is not that much implemented though.



== Logging

=== 3 logs: Debug, Audit and Event logs

**Debug logs** include info of relevance to developers, and includes things
both the _computer_ (source code) does, e.g. method requests, background jobs,
failing over to another node. And includes if this was initiated by a human.
Can be annoyingly detailed and noisy, for anyone not troubleshooting the
computers. Could get shipped off-site.

The **audit log** shows what the *humans* did, and is nice to read, for
auditors.  But it might include sensitive info, e.g. personal details — and so
should not be used for e.g. sending webhooks events. Could get shipped off-site.

The **event log** includes events of interest to the Talkyard users, e.g. for
sending as webhooks. But it would be too sparse, to use for auditing or
debugging. — It's part of the Ty application, and would be exported and
imported together with pages, posts, users etc. Not shipped off-site.
Updates to the event log, might resul in >= 1 debug log messages.

Then there are also **notifications**, which is almost like a log too, but they
are per person, and can be marked as seen, by the person who got the
notification. Whilst events are per whole Ty site.

See e.g.:
https://stackoverflow.com/questions/2492362/difference-in-auditing-and-logging
