Compare commits
2 Commits
77ccc731be
...
ab02758382
| Author | SHA1 | Date | |
|---|---|---|---|
|
ab02758382 | ||
|
|
fbd5c84eca |
674
LICENSE
Normal file
674
LICENSE
Normal file
@@ -0,0 +1,674 @@
|
||||
GNU GENERAL PUBLIC LICENSE
|
||||
Version 3, 29 June 2007
|
||||
|
||||
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
|
||||
Everyone is permitted to copy and distribute verbatim copies
|
||||
of this license document, but changing it is not allowed.
|
||||
|
||||
Preamble
|
||||
|
||||
The GNU General Public License is a free, copyleft license for
|
||||
software and other kinds of works.
|
||||
|
||||
The licenses for most software and other practical works are designed
|
||||
to take away your freedom to share and change the works. By contrast,
|
||||
the GNU General Public License is intended to guarantee your freedom to
|
||||
share and change all versions of a program--to make sure it remains free
|
||||
software for all its users. We, the Free Software Foundation, use the
|
||||
GNU General Public License for most of our software; it applies also to
|
||||
any other work released this way by its authors. You can apply it to
|
||||
your programs, too.
|
||||
|
||||
When we speak of free software, we are referring to freedom, not
|
||||
price. Our General Public Licenses are designed to make sure that you
|
||||
have the freedom to distribute copies of free software (and charge for
|
||||
them if you wish), that you receive source code or can get it if you
|
||||
want it, that you can change the software or use pieces of it in new
|
||||
free programs, and that you know you can do these things.
|
||||
|
||||
To protect your rights, we need to prevent others from denying you
|
||||
these rights or asking you to surrender the rights. Therefore, you have
|
||||
certain responsibilities if you distribute copies of the software, or if
|
||||
you modify it: responsibilities to respect the freedom of others.
|
||||
|
||||
For example, if you distribute copies of such a program, whether
|
||||
gratis or for a fee, you must pass on to the recipients the same
|
||||
freedoms that you received. You must make sure that they, too, receive
|
||||
or can get the source code. And you must show them these terms so they
|
||||
know their rights.
|
||||
|
||||
Developers that use the GNU GPL protect your rights with two steps:
|
||||
(1) assert copyright on the software, and (2) offer you this License
|
||||
giving you legal permission to copy, distribute and/or modify it.
|
||||
|
||||
For the developers' and authors' protection, the GPL clearly explains
|
||||
that there is no warranty for this free software. For both users' and
|
||||
authors' sake, the GPL requires that modified versions be marked as
|
||||
changed, so that their problems will not be attributed erroneously to
|
||||
authors of previous versions.
|
||||
|
||||
Some devices are designed to deny users access to install or run
|
||||
modified versions of the software inside them, although the manufacturer
|
||||
can do so. This is fundamentally incompatible with the aim of
|
||||
protecting users' freedom to change the software. The systematic
|
||||
pattern of such abuse occurs in the area of products for individuals to
|
||||
use, which is precisely where it is most unacceptable. Therefore, we
|
||||
have designed this version of the GPL to prohibit the practice for those
|
||||
products. If such problems arise substantially in other domains, we
|
||||
stand ready to extend this provision to those domains in future versions
|
||||
of the GPL, as needed to protect the freedom of users.
|
||||
|
||||
Finally, every program is threatened constantly by software patents.
|
||||
States should not allow patents to restrict development and use of
|
||||
software on general-purpose computers, but in those that do, we wish to
|
||||
avoid the special danger that patents applied to a free program could
|
||||
make it effectively proprietary. To prevent this, the GPL assures that
|
||||
patents cannot be used to render the program non-free.
|
||||
|
||||
The precise terms and conditions for copying, distribution and
|
||||
modification follow.
|
||||
|
||||
TERMS AND CONDITIONS
|
||||
|
||||
0. Definitions.
|
||||
|
||||
"This License" refers to version 3 of the GNU General Public License.
|
||||
|
||||
"Copyright" also means copyright-like laws that apply to other kinds of
|
||||
works, such as semiconductor masks.
|
||||
|
||||
"The Program" refers to any copyrightable work licensed under this
|
||||
License. Each licensee is addressed as "you". "Licensees" and
|
||||
"recipients" may be individuals or organizations.
|
||||
|
||||
To "modify" a work means to copy from or adapt all or part of the work
|
||||
in a fashion requiring copyright permission, other than the making of an
|
||||
exact copy. The resulting work is called a "modified version" of the
|
||||
earlier work or a work "based on" the earlier work.
|
||||
|
||||
A "covered work" means either the unmodified Program or a work based
|
||||
on the Program.
|
||||
|
||||
To "propagate" a work means to do anything with it that, without
|
||||
permission, would make you directly or secondarily liable for
|
||||
infringement under applicable copyright law, except executing it on a
|
||||
computer or modifying a private copy. Propagation includes copying,
|
||||
distribution (with or without modification), making available to the
|
||||
public, and in some countries other activities as well.
|
||||
|
||||
To "convey" a work means any kind of propagation that enables other
|
||||
parties to make or receive copies. Mere interaction with a user through
|
||||
a computer network, with no transfer of a copy, is not conveying.
|
||||
|
||||
An interactive user interface displays "Appropriate Legal Notices"
|
||||
to the extent that it includes a convenient and prominently visible
|
||||
feature that (1) displays an appropriate copyright notice, and (2)
|
||||
tells the user that there is no warranty for the work (except to the
|
||||
extent that warranties are provided), that licensees may convey the
|
||||
work under this License, and how to view a copy of this License. If
|
||||
the interface presents a list of user commands or options, such as a
|
||||
menu, a prominent item in the list meets this criterion.
|
||||
|
||||
1. Source Code.
|
||||
|
||||
The "source code" for a work means the preferred form of the work
|
||||
for making modifications to it. "Object code" means any non-source
|
||||
form of a work.
|
||||
|
||||
A "Standard Interface" means an interface that either is an official
|
||||
standard defined by a recognized standards body, or, in the case of
|
||||
interfaces specified for a particular programming language, one that
|
||||
is widely used among developers working in that language.
|
||||
|
||||
The "System Libraries" of an executable work include anything, other
|
||||
than the work as a whole, that (a) is included in the normal form of
|
||||
packaging a Major Component, but which is not part of that Major
|
||||
Component, and (b) serves only to enable use of the work with that
|
||||
Major Component, or to implement a Standard Interface for which an
|
||||
implementation is available to the public in source code form. A
|
||||
"Major Component", in this context, means a major essential component
|
||||
(kernel, window system, and so on) of the specific operating system
|
||||
(if any) on which the executable work runs, or a compiler used to
|
||||
produce the work, or an object code interpreter used to run it.
|
||||
|
||||
The "Corresponding Source" for a work in object code form means all
|
||||
the source code needed to generate, install, and (for an executable
|
||||
work) run the object code and to modify the work, including scripts to
|
||||
control those activities. However, it does not include the work's
|
||||
System Libraries, or general-purpose tools or generally available free
|
||||
programs which are used unmodified in performing those activities but
|
||||
which are not part of the work. For example, Corresponding Source
|
||||
includes interface definition files associated with source files for
|
||||
the work, and the source code for shared libraries and dynamically
|
||||
linked subprograms that the work is specifically designed to require,
|
||||
such as by intimate data communication or control flow between those
|
||||
subprograms and other parts of the work.
|
||||
|
||||
The Corresponding Source need not include anything that users
|
||||
can regenerate automatically from other parts of the Corresponding
|
||||
Source.
|
||||
|
||||
The Corresponding Source for a work in source code form is that
|
||||
same work.
|
||||
|
||||
2. Basic Permissions.
|
||||
|
||||
All rights granted under this License are granted for the term of
|
||||
copyright on the Program, and are irrevocable provided the stated
|
||||
conditions are met. This License explicitly affirms your unlimited
|
||||
permission to run the unmodified Program. The output from running a
|
||||
covered work is covered by this License only if the output, given its
|
||||
content, constitutes a covered work. This License acknowledges your
|
||||
rights of fair use or other equivalent, as provided by copyright law.
|
||||
|
||||
You may make, run and propagate covered works that you do not
|
||||
convey, without conditions so long as your license otherwise remains
|
||||
in force. You may convey covered works to others for the sole purpose
|
||||
of having them make modifications exclusively for you, or provide you
|
||||
with facilities for running those works, provided that you comply with
|
||||
the terms of this License in conveying all material for which you do
|
||||
not control copyright. Those thus making or running the covered works
|
||||
for you must do so exclusively on your behalf, under your direction
|
||||
and control, on terms that prohibit them from making any copies of
|
||||
your copyrighted material outside their relationship with you.
|
||||
|
||||
Conveying under any other circumstances is permitted solely under
|
||||
the conditions stated below. Sublicensing is not allowed; section 10
|
||||
makes it unnecessary.
|
||||
|
||||
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
|
||||
|
||||
No covered work shall be deemed part of an effective technological
|
||||
measure under any applicable law fulfilling obligations under article
|
||||
11 of the WIPO copyright treaty adopted on 20 December 1996, or
|
||||
similar laws prohibiting or restricting circumvention of such
|
||||
measures.
|
||||
|
||||
When you convey a covered work, you waive any legal power to forbid
|
||||
circumvention of technological measures to the extent such circumvention
|
||||
is effected by exercising rights under this License with respect to
|
||||
the covered work, and you disclaim any intention to limit operation or
|
||||
modification of the work as a means of enforcing, against the work's
|
||||
users, your or third parties' legal rights to forbid circumvention of
|
||||
technological measures.
|
||||
|
||||
4. Conveying Verbatim Copies.
|
||||
|
||||
You may convey verbatim copies of the Program's source code as you
|
||||
receive it, in any medium, provided that you conspicuously and
|
||||
appropriately publish on each copy an appropriate copyright notice;
|
||||
keep intact all notices stating that this License and any
|
||||
non-permissive terms added in accord with section 7 apply to the code;
|
||||
keep intact all notices of the absence of any warranty; and give all
|
||||
recipients a copy of this License along with the Program.
|
||||
|
||||
You may charge any price or no price for each copy that you convey,
|
||||
and you may offer support or warranty protection for a fee.
|
||||
|
||||
5. Conveying Modified Source Versions.
|
||||
|
||||
You may convey a work based on the Program, or the modifications to
|
||||
produce it from the Program, in the form of source code under the
|
||||
terms of section 4, provided that you also meet all of these conditions:
|
||||
|
||||
a) The work must carry prominent notices stating that you modified
|
||||
it, and giving a relevant date.
|
||||
|
||||
b) The work must carry prominent notices stating that it is
|
||||
released under this License and any conditions added under section
|
||||
7. This requirement modifies the requirement in section 4 to
|
||||
"keep intact all notices".
|
||||
|
||||
c) You must license the entire work, as a whole, under this
|
||||
License to anyone who comes into possession of a copy. This
|
||||
License will therefore apply, along with any applicable section 7
|
||||
additional terms, to the whole of the work, and all its parts,
|
||||
regardless of how they are packaged. This License gives no
|
||||
permission to license the work in any other way, but it does not
|
||||
invalidate such permission if you have separately received it.
|
||||
|
||||
d) If the work has interactive user interfaces, each must display
|
||||
Appropriate Legal Notices; however, if the Program has interactive
|
||||
interfaces that do not display Appropriate Legal Notices, your
|
||||
work need not make them do so.
|
||||
|
||||
A compilation of a covered work with other separate and independent
|
||||
works, which are not by their nature extensions of the covered work,
|
||||
and which are not combined with it such as to form a larger program,
|
||||
in or on a volume of a storage or distribution medium, is called an
|
||||
"aggregate" if the compilation and its resulting copyright are not
|
||||
used to limit the access or legal rights of the compilation's users
|
||||
beyond what the individual works permit. Inclusion of a covered work
|
||||
in an aggregate does not cause this License to apply to the other
|
||||
parts of the aggregate.
|
||||
|
||||
6. Conveying Non-Source Forms.
|
||||
|
||||
You may convey a covered work in object code form under the terms
|
||||
of sections 4 and 5, provided that you also convey the
|
||||
machine-readable Corresponding Source under the terms of this License,
|
||||
in one of these ways:
|
||||
|
||||
a) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by the
|
||||
Corresponding Source fixed on a durable physical medium
|
||||
customarily used for software interchange.
|
||||
|
||||
b) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by a
|
||||
written offer, valid for at least three years and valid for as
|
||||
long as you offer spare parts or customer support for that product
|
||||
model, to give anyone who possesses the object code either (1) a
|
||||
copy of the Corresponding Source for all the software in the
|
||||
product that is covered by this License, on a durable physical
|
||||
medium customarily used for software interchange, for a price no
|
||||
more than your reasonable cost of physically performing this
|
||||
conveying of source, or (2) access to copy the
|
||||
Corresponding Source from a network server at no charge.
|
||||
|
||||
c) Convey individual copies of the object code with a copy of the
|
||||
written offer to provide the Corresponding Source. This
|
||||
alternative is allowed only occasionally and noncommercially, and
|
||||
only if you received the object code with such an offer, in accord
|
||||
with subsection 6b.
|
||||
|
||||
d) Convey the object code by offering access from a designated
|
||||
place (gratis or for a charge), and offer equivalent access to the
|
||||
Corresponding Source in the same way through the same place at no
|
||||
further charge. You need not require recipients to copy the
|
||||
Corresponding Source along with the object code. If the place to
|
||||
copy the object code is a network server, the Corresponding Source
|
||||
may be on a different server (operated by you or a third party)
|
||||
that supports equivalent copying facilities, provided you maintain
|
||||
clear directions next to the object code saying where to find the
|
||||
Corresponding Source. Regardless of what server hosts the
|
||||
Corresponding Source, you remain obligated to ensure that it is
|
||||
available for as long as needed to satisfy these requirements.
|
||||
|
||||
e) Convey the object code using peer-to-peer transmission, provided
|
||||
you inform other peers where the object code and Corresponding
|
||||
Source of the work are being offered to the general public at no
|
||||
charge under subsection 6d.
|
||||
|
||||
A separable portion of the object code, whose source code is excluded
|
||||
from the Corresponding Source as a System Library, need not be
|
||||
included in conveying the object code work.
|
||||
|
||||
A "User Product" is either (1) a "consumer product", which means any
|
||||
tangible personal property which is normally used for personal, family,
|
||||
or household purposes, or (2) anything designed or sold for incorporation
|
||||
into a dwelling. In determining whether a product is a consumer product,
|
||||
doubtful cases shall be resolved in favor of coverage. For a particular
|
||||
product received by a particular user, "normally used" refers to a
|
||||
typical or common use of that class of product, regardless of the status
|
||||
of the particular user or of the way in which the particular user
|
||||
actually uses, or expects or is expected to use, the product. A product
|
||||
is a consumer product regardless of whether the product has substantial
|
||||
commercial, industrial or non-consumer uses, unless such uses represent
|
||||
the only significant mode of use of the product.
|
||||
|
||||
"Installation Information" for a User Product means any methods,
|
||||
procedures, authorization keys, or other information required to install
|
||||
and execute modified versions of a covered work in that User Product from
|
||||
a modified version of its Corresponding Source. The information must
|
||||
suffice to ensure that the continued functioning of the modified object
|
||||
code is in no case prevented or interfered with solely because
|
||||
modification has been made.
|
||||
|
||||
If you convey an object code work under this section in, or with, or
|
||||
specifically for use in, a User Product, and the conveying occurs as
|
||||
part of a transaction in which the right of possession and use of the
|
||||
User Product is transferred to the recipient in perpetuity or for a
|
||||
fixed term (regardless of how the transaction is characterized), the
|
||||
Corresponding Source conveyed under this section must be accompanied
|
||||
by the Installation Information. But this requirement does not apply
|
||||
if neither you nor any third party retains the ability to install
|
||||
modified object code on the User Product (for example, the work has
|
||||
been installed in ROM).
|
||||
|
||||
The requirement to provide Installation Information does not include a
|
||||
requirement to continue to provide support service, warranty, or updates
|
||||
for a work that has been modified or installed by the recipient, or for
|
||||
the User Product in which it has been modified or installed. Access to a
|
||||
network may be denied when the modification itself materially and
|
||||
adversely affects the operation of the network or violates the rules and
|
||||
protocols for communication across the network.
|
||||
|
||||
Corresponding Source conveyed, and Installation Information provided,
|
||||
in accord with this section must be in a format that is publicly
|
||||
documented (and with an implementation available to the public in
|
||||
source code form), and must require no special password or key for
|
||||
unpacking, reading or copying.
|
||||
|
||||
7. Additional Terms.
|
||||
|
||||
"Additional permissions" are terms that supplement the terms of this
|
||||
License by making exceptions from one or more of its conditions.
|
||||
Additional permissions that are applicable to the entire Program shall
|
||||
be treated as though they were included in this License, to the extent
|
||||
that they are valid under applicable law. If additional permissions
|
||||
apply only to part of the Program, that part may be used separately
|
||||
under those permissions, but the entire Program remains governed by
|
||||
this License without regard to the additional permissions.
|
||||
|
||||
When you convey a copy of a covered work, you may at your option
|
||||
remove any additional permissions from that copy, or from any part of
|
||||
it. (Additional permissions may be written to require their own
|
||||
removal in certain cases when you modify the work.) You may place
|
||||
additional permissions on material, added by you to a covered work,
|
||||
for which you have or can give appropriate copyright permission.
|
||||
|
||||
Notwithstanding any other provision of this License, for material you
|
||||
add to a covered work, you may (if authorized by the copyright holders of
|
||||
that material) supplement the terms of this License with terms:
|
||||
|
||||
a) Disclaiming warranty or limiting liability differently from the
|
||||
terms of sections 15 and 16 of this License; or
|
||||
|
||||
b) Requiring preservation of specified reasonable legal notices or
|
||||
author attributions in that material or in the Appropriate Legal
|
||||
Notices displayed by works containing it; or
|
||||
|
||||
c) Prohibiting misrepresentation of the origin of that material, or
|
||||
requiring that modified versions of such material be marked in
|
||||
reasonable ways as different from the original version; or
|
||||
|
||||
d) Limiting the use for publicity purposes of names of licensors or
|
||||
authors of the material; or
|
||||
|
||||
e) Declining to grant rights under trademark law for use of some
|
||||
trade names, trademarks, or service marks; or
|
||||
|
||||
f) Requiring indemnification of licensors and authors of that
|
||||
material by anyone who conveys the material (or modified versions of
|
||||
it) with contractual assumptions of liability to the recipient, for
|
||||
any liability that these contractual assumptions directly impose on
|
||||
those licensors and authors.
|
||||
|
||||
All other non-permissive additional terms are considered "further
|
||||
restrictions" within the meaning of section 10. If the Program as you
|
||||
received it, or any part of it, contains a notice stating that it is
|
||||
governed by this License along with a term that is a further
|
||||
restriction, you may remove that term. If a license document contains
|
||||
a further restriction but permits relicensing or conveying under this
|
||||
License, you may add to a covered work material governed by the terms
|
||||
of that license document, provided that the further restriction does
|
||||
not survive such relicensing or conveying.
|
||||
|
||||
If you add terms to a covered work in accord with this section, you
|
||||
must place, in the relevant source files, a statement of the
|
||||
additional terms that apply to those files, or a notice indicating
|
||||
where to find the applicable terms.
|
||||
|
||||
Additional terms, permissive or non-permissive, may be stated in the
|
||||
form of a separately written license, or stated as exceptions;
|
||||
the above requirements apply either way.
|
||||
|
||||
8. Termination.
|
||||
|
||||
You may not propagate or modify a covered work except as expressly
|
||||
provided under this License. Any attempt otherwise to propagate or
|
||||
modify it is void, and will automatically terminate your rights under
|
||||
this License (including any patent licenses granted under the third
|
||||
paragraph of section 11).
|
||||
|
||||
However, if you cease all violation of this License, then your
|
||||
license from a particular copyright holder is reinstated (a)
|
||||
provisionally, unless and until the copyright holder explicitly and
|
||||
finally terminates your license, and (b) permanently, if the copyright
|
||||
holder fails to notify you of the violation by some reasonable means
|
||||
prior to 60 days after the cessation.
|
||||
|
||||
Moreover, your license from a particular copyright holder is
|
||||
reinstated permanently if the copyright holder notifies you of the
|
||||
violation by some reasonable means, this is the first time you have
|
||||
received notice of violation of this License (for any work) from that
|
||||
copyright holder, and you cure the violation prior to 30 days after
|
||||
your receipt of the notice.
|
||||
|
||||
Termination of your rights under this section does not terminate the
|
||||
licenses of parties who have received copies or rights from you under
|
||||
this License. If your rights have been terminated and not permanently
|
||||
reinstated, you do not qualify to receive new licenses for the same
|
||||
material under section 10.
|
||||
|
||||
9. Acceptance Not Required for Having Copies.
|
||||
|
||||
You are not required to accept this License in order to receive or
|
||||
run a copy of the Program. Ancillary propagation of a covered work
|
||||
occurring solely as a consequence of using peer-to-peer transmission
|
||||
to receive a copy likewise does not require acceptance. However,
|
||||
nothing other than this License grants you permission to propagate or
|
||||
modify any covered work. These actions infringe copyright if you do
|
||||
not accept this License. Therefore, by modifying or propagating a
|
||||
covered work, you indicate your acceptance of this License to do so.
|
||||
|
||||
10. Automatic Licensing of Downstream Recipients.
|
||||
|
||||
Each time you convey a covered work, the recipient automatically
|
||||
receives a license from the original licensors, to run, modify and
|
||||
propagate that work, subject to this License. You are not responsible
|
||||
for enforcing compliance by third parties with this License.
|
||||
|
||||
An "entity transaction" is a transaction transferring control of an
|
||||
organization, or substantially all assets of one, or subdividing an
|
||||
organization, or merging organizations. If propagation of a covered
|
||||
work results from an entity transaction, each party to that
|
||||
transaction who receives a copy of the work also receives whatever
|
||||
licenses to the work the party's predecessor in interest had or could
|
||||
give under the previous paragraph, plus a right to possession of the
|
||||
Corresponding Source of the work from the predecessor in interest, if
|
||||
the predecessor has it or can get it with reasonable efforts.
|
||||
|
||||
You may not impose any further restrictions on the exercise of the
|
||||
rights granted or affirmed under this License. For example, you may
|
||||
not impose a license fee, royalty, or other charge for exercise of
|
||||
rights granted under this License, and you may not initiate litigation
|
||||
(including a cross-claim or counterclaim in a lawsuit) alleging that
|
||||
any patent claim is infringed by making, using, selling, offering for
|
||||
sale, or importing the Program or any portion of it.
|
||||
|
||||
11. Patents.
|
||||
|
||||
A "contributor" is a copyright holder who authorizes use under this
|
||||
License of the Program or a work on which the Program is based. The
|
||||
work thus licensed is called the contributor's "contributor version".
|
||||
|
||||
A contributor's "essential patent claims" are all patent claims
|
||||
owned or controlled by the contributor, whether already acquired or
|
||||
hereafter acquired, that would be infringed by some manner, permitted
|
||||
by this License, of making, using, or selling its contributor version,
|
||||
but do not include claims that would be infringed only as a
|
||||
consequence of further modification of the contributor version. For
|
||||
purposes of this definition, "control" includes the right to grant
|
||||
patent sublicenses in a manner consistent with the requirements of
|
||||
this License.
|
||||
|
||||
Each contributor grants you a non-exclusive, worldwide, royalty-free
|
||||
patent license under the contributor's essential patent claims, to
|
||||
make, use, sell, offer for sale, import and otherwise run, modify and
|
||||
propagate the contents of its contributor version.
|
||||
|
||||
In the following three paragraphs, a "patent license" is any express
|
||||
agreement or commitment, however denominated, not to enforce a patent
|
||||
(such as an express permission to practice a patent or covenant not to
|
||||
sue for patent infringement). To "grant" such a patent license to a
|
||||
party means to make such an agreement or commitment not to enforce a
|
||||
patent against the party.
|
||||
|
||||
If you convey a covered work, knowingly relying on a patent license,
|
||||
and the Corresponding Source of the work is not available for anyone
|
||||
to copy, free of charge and under the terms of this License, through a
|
||||
publicly available network server or other readily accessible means,
|
||||
then you must either (1) cause the Corresponding Source to be so
|
||||
available, or (2) arrange to deprive yourself of the benefit of the
|
||||
patent license for this particular work, or (3) arrange, in a manner
|
||||
consistent with the requirements of this License, to extend the patent
|
||||
license to downstream recipients. "Knowingly relying" means you have
|
||||
actual knowledge that, but for the patent license, your conveying the
|
||||
covered work in a country, or your recipient's use of the covered work
|
||||
in a country, would infringe one or more identifiable patents in that
|
||||
country that you have reason to believe are valid.
|
||||
|
||||
If, pursuant to or in connection with a single transaction or
|
||||
arrangement, you convey, or propagate by procuring conveyance of, a
|
||||
covered work, and grant a patent license to some of the parties
|
||||
receiving the covered work authorizing them to use, propagate, modify
|
||||
or convey a specific copy of the covered work, then the patent license
|
||||
you grant is automatically extended to all recipients of the covered
|
||||
work and works based on it.
|
||||
|
||||
A patent license is "discriminatory" if it does not include within
|
||||
the scope of its coverage, prohibits the exercise of, or is
|
||||
conditioned on the non-exercise of one or more of the rights that are
|
||||
specifically granted under this License. You may not convey a covered
|
||||
work if you are a party to an arrangement with a third party that is
|
||||
in the business of distributing software, under which you make payment
|
||||
to the third party based on the extent of your activity of conveying
|
||||
the work, and under which the third party grants, to any of the
|
||||
parties who would receive the covered work from you, a discriminatory
|
||||
patent license (a) in connection with copies of the covered work
|
||||
conveyed by you (or copies made from those copies), or (b) primarily
|
||||
for and in connection with specific products or compilations that
|
||||
contain the covered work, unless you entered into that arrangement,
|
||||
or that patent license was granted, prior to 28 March 2007.
|
||||
|
||||
Nothing in this License shall be construed as excluding or limiting
|
||||
any implied license or other defenses to infringement that may
|
||||
otherwise be available to you under applicable patent law.
|
||||
|
||||
12. No Surrender of Others' Freedom.
|
||||
|
||||
If conditions are imposed on you (whether by court order, agreement or
|
||||
otherwise) that contradict the conditions of this License, they do not
|
||||
excuse you from the conditions of this License. If you cannot convey a
|
||||
covered work so as to satisfy simultaneously your obligations under this
|
||||
License and any other pertinent obligations, then as a consequence you may
|
||||
not convey it at all. For example, if you agree to terms that obligate you
|
||||
to collect a royalty for further conveying from those to whom you convey
|
||||
the Program, the only way you could satisfy both those terms and this
|
||||
License would be to refrain entirely from conveying the Program.
|
||||
|
||||
13. Use with the GNU Affero General Public License.
|
||||
|
||||
Notwithstanding any other provision of this License, you have
|
||||
permission to link or combine any covered work with a work licensed
|
||||
under version 3 of the GNU Affero General Public License into a single
|
||||
combined work, and to convey the resulting work. The terms of this
|
||||
License will continue to apply to the part which is the covered work,
|
||||
but the special requirements of the GNU Affero General Public License,
|
||||
section 13, concerning interaction through a network will apply to the
|
||||
combination as such.
|
||||
|
||||
14. Revised Versions of this License.
|
||||
|
||||
The Free Software Foundation may publish revised and/or new versions of
|
||||
the GNU General Public License from time to time. Such new versions will
|
||||
be similar in spirit to the present version, but may differ in detail to
|
||||
address new problems or concerns.
|
||||
|
||||
Each version is given a distinguishing version number. If the
|
||||
Program specifies that a certain numbered version of the GNU General
|
||||
Public License "or any later version" applies to it, you have the
|
||||
option of following the terms and conditions either of that numbered
|
||||
version or of any later version published by the Free Software
|
||||
Foundation. If the Program does not specify a version number of the
|
||||
GNU General Public License, you may choose any version ever published
|
||||
by the Free Software Foundation.
|
||||
|
||||
If the Program specifies that a proxy can decide which future
|
||||
versions of the GNU General Public License can be used, that proxy's
|
||||
public statement of acceptance of a version permanently authorizes you
|
||||
to choose that version for the Program.
|
||||
|
||||
Later license versions may give you additional or different
|
||||
permissions. However, no additional obligations are imposed on any
|
||||
author or copyright holder as a result of your choosing to follow a
|
||||
later version.
|
||||
|
||||
15. Disclaimer of Warranty.
|
||||
|
||||
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
|
||||
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
|
||||
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
|
||||
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
|
||||
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
||||
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
|
||||
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
|
||||
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
|
||||
|
||||
16. Limitation of Liability.
|
||||
|
||||
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
|
||||
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
|
||||
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
|
||||
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
|
||||
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
|
||||
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
|
||||
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
|
||||
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
|
||||
SUCH DAMAGES.
|
||||
|
||||
17. Interpretation of Sections 15 and 16.
|
||||
|
||||
If the disclaimer of warranty and limitation of liability provided
|
||||
above cannot be given local legal effect according to their terms,
|
||||
reviewing courts shall apply local law that most closely approximates
|
||||
an absolute waiver of all civil liability in connection with the
|
||||
Program, unless a warranty or assumption of liability accompanies a
|
||||
copy of the Program in return for a fee.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
How to Apply These Terms to Your New Programs
|
||||
|
||||
If you develop a new program, and you want it to be of the greatest
|
||||
possible use to the public, the best way to achieve this is to make it
|
||||
free software which everyone can redistribute and change under these terms.
|
||||
|
||||
To do so, attach the following notices to the program. It is safest
|
||||
to attach them to the start of each source file to most effectively
|
||||
state the exclusion of warranty; and each file should have at least
|
||||
the "copyright" line and a pointer to where the full notice is found.
|
||||
|
||||
<one line to give the program's name and a brief idea of what it does.>
|
||||
Copyright (C) <year> <name of author>
|
||||
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation, either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
Also add information on how to contact you by electronic and paper mail.
|
||||
|
||||
If the program does terminal interaction, make it output a short
|
||||
notice like this when it starts in an interactive mode:
|
||||
|
||||
<program> Copyright (C) <year> <name of author>
|
||||
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
|
||||
This is free software, and you are welcome to redistribute it
|
||||
under certain conditions; type `show c' for details.
|
||||
|
||||
The hypothetical commands `show w' and `show c' should show the appropriate
|
||||
parts of the General Public License. Of course, your program's commands
|
||||
might be different; for a GUI interface, you would use an "about box".
|
||||
|
||||
You should also get your employer (if you work as a programmer) or school,
|
||||
if any, to sign a "copyright disclaimer" for the program, if necessary.
|
||||
For more information on this, and how to apply and follow the GNU GPL, see
|
||||
<https://www.gnu.org/licenses/>.
|
||||
|
||||
The GNU General Public License does not permit incorporating your program
|
||||
into proprietary programs. If your program is a subroutine library, you
|
||||
may consider it more useful to permit linking proprietary applications with
|
||||
the library. If this is what you want to do, use the GNU Lesser General
|
||||
Public License instead of this License. But first, please read
|
||||
<https://www.gnu.org/licenses/why-not-lgpl.html>.
|
||||
24
README.md
Normal file
24
README.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# DreamChat
|
||||
|
||||
## Overview
|
||||
|
||||
This project is designed to simulate characters, enable interactive conversations with them, and generate stories based on user-provided templates and backgrounds. The platform focuses on creating immersive, personalized fan-like experiences where users can interact with their favorite simulated personas.
|
||||
|
||||
## Core Features
|
||||
|
||||
- Character Simulation: Users can define and customize characters with attributes, personalities, and backstories.
|
||||
- Interactive Dialogue: The main focus is enabling users to talk directly to their simulated characters, using chat data provided by the user.
|
||||
- Story Generation: The system generates narratives based on user-defined templates, backgrounds, and character interactions.
|
||||
- User Data Import: Users can import their own chat histories, blogs, or other text data to enrich character simulation and personalize interactions.
|
||||
|
||||
## Key Requirements
|
||||
|
||||
User-Centric Design: Prioritize ease of use, intuitive character creation, and natural conversational flow.
|
||||
|
||||
## Target Audience
|
||||
|
||||
- Storytellers and roleplayers seeking immersive character-driven narratives.
|
||||
|
||||
## Goals
|
||||
|
||||
Deliver a platform where users can define, interact, and narrate with their characters.
|
||||
44
doc/README.md
Normal file
44
doc/README.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# DreamChat Project Documentation
|
||||
|
||||
This directory contains comprehensive planning and implementation documentation for the DreamChat project.
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [architecture.md](./architecture.md) | System architecture, tech stack, component diagrams |
|
||||
| [monorepo-guide.md](./monorepo-guide.md) | pnpm workspace setup, shared packages |
|
||||
| [database-schema.md](./database-schema.md) | PostgreSQL schema, vector store design, entities |
|
||||
| [api-spec.md](./api-spec.md) | REST API & WebSocket specifications, OpenAPI |
|
||||
| [implementation-plan.md](./implementation-plan.md) | Phased roadmap, milestones, deliverables |
|
||||
| [frontend-guide.md](./frontend-guide.md) | Frontend architecture, component hierarchy |
|
||||
| [deployment.md](./deployment.md) | Docker Compose, devcontainer, deployment guide |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Tech Stack
|
||||
- **Backend**: NestJS (TypeScript)
|
||||
- **Frontend**: React + Vite (TypeScript)
|
||||
- **Package Manager**: pnpm (monorepo workspaces)
|
||||
- **Database**: PostgreSQL with pgvector
|
||||
- **ORM**: Prisma
|
||||
- **Vector Store**: PostgreSQL (pgvector) + LangChain + Local HuggingFace Embeddings
|
||||
- **LLM**: OpenRouter (flexible adapter pattern)
|
||||
- **Real-time**: WebSocket (shared types package)
|
||||
- **Auth**: Keycloak + Password-based
|
||||
- **Web Scraping**: Puppeteer/Playwright (headless browser)
|
||||
|
||||
### Implementation Phases
|
||||
1. **MVP**: Single character chat with memory
|
||||
2. **Phase 2**: Story generation with branching tree view
|
||||
3. **Phase 3**: Multi-character group chat
|
||||
|
||||
### Key Design Patterns
|
||||
- **Adapter Pattern**: LLM providers, data import sources
|
||||
- **Repository Pattern**: Database access
|
||||
- **Strategy Pattern**: Predefined web scrapers
|
||||
- **Observer Pattern**: WebSocket events
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-02-23*
|
||||
572
doc/api-spec.md
Normal file
572
doc/api-spec.md
Normal file
@@ -0,0 +1,572 @@
|
||||
# DreamChat API Specification
|
||||
|
||||
## Overview
|
||||
|
||||
This document defines the REST API and WebSocket specifications for DreamChat.
|
||||
|
||||
- **REST API**: For CRUD operations, file uploads, and synchronous requests
|
||||
- **WebSocket**: For real-time chat streaming
|
||||
- **OpenAPI**: Auto-generated from NestJS decorators for frontend client generation
|
||||
|
||||
## Base URL
|
||||
|
||||
```
|
||||
Development: http://localhost:3000/api
|
||||
Production: https://api.dreamchat.example/api
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
### JWT Token Flow
|
||||
|
||||
```http
|
||||
POST /api/auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "user@example.com",
|
||||
"password": "securepassword"
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"expiresIn": 3600
|
||||
}
|
||||
```
|
||||
|
||||
### Keycloak Integration
|
||||
|
||||
```http
|
||||
GET /api/auth/keycloak
|
||||
Redirect to Keycloak login
|
||||
|
||||
Callback:
|
||||
GET /api/auth/keycloak/callback?code=...
|
||||
Response: { accessToken, refreshToken, expiresIn }
|
||||
```
|
||||
|
||||
### WebSocket Auth
|
||||
|
||||
WebSocket connections authenticate via query parameter:
|
||||
```
|
||||
ws://localhost:3000/chat?token=eyJhbGciOiJIUzI1NiIs...
|
||||
```
|
||||
|
||||
## REST API Endpoints
|
||||
|
||||
### Authentication Module
|
||||
|
||||
| Method | Endpoint | Description | Auth |
|
||||
|--------|----------|-------------|------|
|
||||
| POST | `/auth/login` | Local login | Public |
|
||||
| POST | `/auth/refresh` | Refresh token | Public |
|
||||
| POST | `/auth/logout` | Logout | Bearer |
|
||||
| GET | `/auth/me` | Get current user | Bearer |
|
||||
| GET | `/auth/keycloak` | Keycloak login URL | Public |
|
||||
| GET | `/auth/keycloak/callback` | Keycloak callback | Public |
|
||||
|
||||
### Users Module
|
||||
|
||||
| Method | Endpoint | Description | Auth |
|
||||
|--------|----------|-------------|------|
|
||||
| POST | `/users` | Register new user | Public |
|
||||
| GET | `/users/:id` | Get user profile | Bearer |
|
||||
| PATCH | `/users/:id` | Update user | Bearer (own only) |
|
||||
| DELETE | `/users/:id` | Delete user | Bearer (own/admin) |
|
||||
|
||||
### Characters Module
|
||||
|
||||
```typescript
|
||||
// DTOs
|
||||
class CreateCharacterDto {
|
||||
name: string;
|
||||
personalityPrompt: string;
|
||||
backstory?: string;
|
||||
attributes?: Record<string, any>;
|
||||
avatarUrl?: string;
|
||||
config?: Record<string, any>;
|
||||
}
|
||||
|
||||
class CharacterResponseDto {
|
||||
id: string;
|
||||
name: string;
|
||||
avatarUrl: string;
|
||||
personalityPrompt: string;
|
||||
backstory: string;
|
||||
attributes: Record<string, any>;
|
||||
createdAt: Date;
|
||||
}
|
||||
```
|
||||
|
||||
| Method | Endpoint | Description | Auth |
|
||||
|--------|----------|-------------|------|
|
||||
| GET | `/characters` | List user's characters | Bearer |
|
||||
| POST | `/characters` | Create character | Bearer |
|
||||
| GET | `/characters/:id` | Get character details | Bearer |
|
||||
| PATCH | `/characters/:id` | Update character | Bearer (owner) |
|
||||
| DELETE | `/characters/:id` | Delete character | Bearer (owner) |
|
||||
|
||||
**Example Requests:**
|
||||
|
||||
```http
|
||||
POST /api/characters
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "Alice",
|
||||
"personalityPrompt": "You are Alice, a curious and adventurous explorer...",
|
||||
"backstory": "Alice grew up in a small village...",
|
||||
"attributes": {
|
||||
"traits": ["curious", "brave", "witty"],
|
||||
"age": 25,
|
||||
"species": "human",
|
||||
"skills": ["navigation", "survival"]
|
||||
}
|
||||
}
|
||||
|
||||
Response: 201 Created
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "Alice",
|
||||
"personalityPrompt": "...",
|
||||
"attributes": { ... },
|
||||
"createdAt": "2026-02-23T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Conversations Module
|
||||
|
||||
```typescript
|
||||
class CreateConversationDto {
|
||||
characterId: string;
|
||||
title?: string;
|
||||
}
|
||||
|
||||
class ConversationResponseDto {
|
||||
id: string;
|
||||
title: string;
|
||||
character: CharacterSummaryDto;
|
||||
messageCount: number;
|
||||
createdAt: Date;
|
||||
}
|
||||
```
|
||||
|
||||
| Method | Endpoint | Description | Auth |
|
||||
|--------|----------|-------------|------|
|
||||
| GET | `/conversations` | List conversations | Bearer |
|
||||
| POST | `/conversations` | Create conversation | Bearer |
|
||||
| GET | `/conversations/:id` | Get conversation | Bearer |
|
||||
| PATCH | `/conversations/:id` | Update conversation | Bearer |
|
||||
| DELETE | `/conversations/:id` | Delete conversation | Bearer |
|
||||
|
||||
### Messages Module
|
||||
|
||||
```typescript
|
||||
class CreateMessageDto {
|
||||
content: string;
|
||||
}
|
||||
|
||||
class MessageResponseDto {
|
||||
id: string;
|
||||
role: 'user' | 'assistant';
|
||||
content: string;
|
||||
tokensUsed?: number;
|
||||
model?: string;
|
||||
createdAt: Date;
|
||||
}
|
||||
```
|
||||
|
||||
| Method | Endpoint | Description | Auth |
|
||||
|--------|----------|-------------|------|
|
||||
| GET | `/conversations/:id/messages` | Get messages (paginated) | Bearer |
|
||||
| POST | `/conversations/:id/messages` | Send message (non-streaming) | Bearer |
|
||||
| DELETE | `/messages/:id` | Delete message | Bearer |
|
||||
|
||||
### Import Module
|
||||
|
||||
```typescript
|
||||
class FileImportDto {
|
||||
// Multipart form data
|
||||
file: File;
|
||||
}
|
||||
|
||||
class UrlImportDto {
|
||||
url: string;
|
||||
}
|
||||
|
||||
class ImportResponseDto {
|
||||
id: string;
|
||||
status: 'pending' | 'processing' | 'completed' | 'failed';
|
||||
sourceName: string;
|
||||
fileSize?: number;
|
||||
content?: string;
|
||||
errorMessage?: string;
|
||||
createdAt: Date;
|
||||
}
|
||||
```
|
||||
|
||||
| Method | Endpoint | Description | Auth |
|
||||
|--------|----------|-------------|------|
|
||||
| POST | `/import/file` | Import file (txt, pdf, md) | Bearer |
|
||||
| POST | `/import/url` | Import from URL | Bearer |
|
||||
| GET | `/import/:id` | Get import status | Bearer |
|
||||
| GET | `/import` | List imports | Bearer |
|
||||
| DELETE | `/import/:id` | Delete import | Bearer |
|
||||
|
||||
**File Upload Request:**
|
||||
|
||||
```http
|
||||
POST /api/import/file
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: multipart/form-data
|
||||
|
||||
------Boundary
|
||||
Content-Disposition: form-data; name="file"; filename="story.txt"
|
||||
Content-Type: text/plain
|
||||
|
||||
(file content here)
|
||||
------Boundary--
|
||||
|
||||
Response: 202 Accepted
|
||||
{
|
||||
"id": "import-uuid",
|
||||
"status": "processing",
|
||||
"sourceName": "story.txt",
|
||||
"createdAt": "2026-02-23T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**URL Import Request:**
|
||||
|
||||
```http
|
||||
POST /api/import/url
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"url": "https://archiveofourown.org/works/12345678"
|
||||
}
|
||||
|
||||
Response: 202 Accepted
|
||||
{
|
||||
"id": "import-uuid",
|
||||
"status": "processing",
|
||||
"sourceName": "https://archiveofourown.org/works/12345678"
|
||||
}
|
||||
|
||||
// If no scraper available:
|
||||
Response: 400 Bad Request
|
||||
{
|
||||
"error": "UNSUPPORTED_URL",
|
||||
"message": "No scraper available for this URL"
|
||||
}
|
||||
```
|
||||
|
||||
### Story Module (Phase 2)
|
||||
|
||||
```typescript
|
||||
class CreateStoryBranchDto {
|
||||
parentId?: string; // null for root
|
||||
userDirection: string;
|
||||
}
|
||||
|
||||
class StoryBranchResponseDto {
|
||||
id: string;
|
||||
conversationId: string;
|
||||
parentId?: string;
|
||||
title: string;
|
||||
content: string;
|
||||
userDirection: string;
|
||||
depth: number;
|
||||
children: StoryBranchResponseDto[];
|
||||
createdAt: Date;
|
||||
}
|
||||
```
|
||||
|
||||
| Method | Endpoint | Description | Auth |
|
||||
|--------|----------|-------------|------|
|
||||
| GET | `/conversations/:id/story` | Get story tree | Bearer |
|
||||
| POST | `/conversations/:id/story/branches` | Create new branch | Bearer |
|
||||
| GET | `/story-branches/:id` | Get branch details | Bearer |
|
||||
| PATCH | `/story-branches/:id` | Update branch | Bearer |
|
||||
| DELETE | `/story-branches/:id` | Delete branch | Bearer |
|
||||
|
||||
**Get Story Tree:**
|
||||
|
||||
```http
|
||||
GET /api/conversations/conv-id/story
|
||||
Authorization: Bearer {token}
|
||||
|
||||
Response:
|
||||
{
|
||||
"root": {
|
||||
"id": "root-uuid",
|
||||
"title": "The Beginning",
|
||||
"content": "Once upon a time...",
|
||||
"depth": 0,
|
||||
"children": [
|
||||
{
|
||||
"id": "branch-1",
|
||||
"title": "The Left Path",
|
||||
"content": "You chose the left path...",
|
||||
"userDirection": "Go left into the dark forest",
|
||||
"depth": 1,
|
||||
"children": []
|
||||
},
|
||||
{
|
||||
"id": "branch-2",
|
||||
"title": "The Right Path",
|
||||
"content": "You chose the right path...",
|
||||
"userDirection": "Go right towards the castle",
|
||||
"depth": 1,
|
||||
"children": []
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Multi-Character Module (Phase 3)
|
||||
|
||||
```typescript
|
||||
class AddParticipantDto {
|
||||
characterId: string;
|
||||
autoRespond: boolean;
|
||||
}
|
||||
|
||||
class ParticipantResponseDto {
|
||||
id: string;
|
||||
character: CharacterSummaryDto;
|
||||
isActive: boolean;
|
||||
autoRespond: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
| Method | Endpoint | Description | Auth |
|
||||
|--------|----------|-------------|------|
|
||||
| GET | `/conversations/:id/participants` | List participants | Bearer |
|
||||
| POST | `/conversations/:id/participants` | Add participant | Bearer |
|
||||
| DELETE | `/conversations/:id/participants/:charId` | Remove participant | Bearer |
|
||||
|
||||
## WebSocket Specification
|
||||
|
||||
### Connection
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('ws://localhost:3000/chat?token=JWT_TOKEN');
|
||||
|
||||
ws.onopen = () => {
|
||||
console.log('Connected');
|
||||
};
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
const message = JSON.parse(event.data);
|
||||
handleMessage(message);
|
||||
};
|
||||
```
|
||||
|
||||
### Message Protocol
|
||||
|
||||
All WebSocket messages use JSON format:
|
||||
|
||||
```typescript
|
||||
interface WebSocketMessage {
|
||||
type: string;
|
||||
payload: any;
|
||||
timestamp: string;
|
||||
requestId?: string; // For correlating responses
|
||||
}
|
||||
```
|
||||
|
||||
### Client → Server Events
|
||||
|
||||
#### 1. Join Conversation
|
||||
|
||||
```typescript
|
||||
// Join a conversation room
|
||||
{
|
||||
"type": "JOIN_CONVERSATION",
|
||||
"payload": {
|
||||
"conversationId": "conv-uuid"
|
||||
},
|
||||
"requestId": "req-123"
|
||||
}
|
||||
|
||||
// Response
|
||||
{
|
||||
"type": "CONVERSATION_JOINED",
|
||||
"payload": {
|
||||
"conversationId": "conv-uuid",
|
||||
"history": [ /* last N messages */ ]
|
||||
},
|
||||
"requestId": "req-123"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Send Message (Streaming)
|
||||
|
||||
```typescript
|
||||
{
|
||||
"type": "SEND_MESSAGE",
|
||||
"payload": {
|
||||
"conversationId": "conv-uuid",
|
||||
"content": "Hello, how are you?",
|
||||
"streaming": true // Enable streaming response
|
||||
},
|
||||
"requestId": "msg-456"
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Stop Generation
|
||||
|
||||
```typescript
|
||||
{
|
||||
"type": "STOP_GENERATION",
|
||||
"payload": {
|
||||
"conversationId": "conv-uuid"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. Leave Conversation
|
||||
|
||||
```typescript
|
||||
{
|
||||
"type": "LEAVE_CONVERSATION",
|
||||
"payload": {
|
||||
"conversationId": "conv-uuid"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Server → Client Events
|
||||
|
||||
#### 1. Message Acknowledged
|
||||
|
||||
```typescript
|
||||
{
|
||||
"type": "MESSAGE_ACK",
|
||||
"payload": {
|
||||
"messageId": "msg-uuid",
|
||||
"status": "received"
|
||||
},
|
||||
"requestId": "msg-456"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Stream Chunk
|
||||
|
||||
```typescript
|
||||
{
|
||||
"type": "STREAM_CHUNK",
|
||||
"payload": {
|
||||
"conversationId": "conv-uuid",
|
||||
"chunk": " part of response",
|
||||
"isComplete": false
|
||||
},
|
||||
"requestId": "msg-456"
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Stream Complete
|
||||
|
||||
```typescript
|
||||
{
|
||||
"type": "STREAM_COMPLETE",
|
||||
"payload": {
|
||||
"conversationId": "conv-uuid",
|
||||
"messageId": "assistant-msg-uuid",
|
||||
"content": "Full response text",
|
||||
"tokensUsed": 150,
|
||||
"model": "openai/gpt-4o"
|
||||
},
|
||||
"requestId": "msg-456"
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. Error
|
||||
|
||||
```typescript
|
||||
{
|
||||
"type": "ERROR",
|
||||
"payload": {
|
||||
"code": "LLM_ERROR",
|
||||
"message": "Failed to generate response",
|
||||
"details": { ... }
|
||||
},
|
||||
"requestId": "msg-456"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Codes
|
||||
|
||||
| Code | Description | HTTP Status |
|
||||
|------|-------------|-------------|
|
||||
| `UNAUTHORIZED` | Invalid or expired token | 401 |
|
||||
| `FORBIDDEN` | Insufficient permissions | 403 |
|
||||
| `NOT_FOUND` | Resource not found | 404 |
|
||||
| `VALIDATION_ERROR` | Invalid input data | 400 |
|
||||
| `LLM_ERROR` | LLM provider error | 502 |
|
||||
| `RATE_LIMITED` | Too many requests | 429 |
|
||||
| `FILE_TOO_LARGE` | File exceeds 50MB | 413 |
|
||||
| `UNSUPPORTED_URL` | No scraper for URL | 400 |
|
||||
|
||||
## OpenAPI Configuration
|
||||
|
||||
### NestJS Setup
|
||||
|
||||
```typescript
|
||||
// main.ts
|
||||
const config = new DocumentBuilder()
|
||||
.setTitle('DreamChat API')
|
||||
.setDescription('Character simulation and chat API')
|
||||
.setVersion('1.0')
|
||||
.addBearerAuth()
|
||||
.addTag('auth', 'Authentication endpoints')
|
||||
.addTag('users', 'User management')
|
||||
.addTag('characters', 'Character CRUD')
|
||||
.addTag('conversations', 'Chat sessions')
|
||||
.addTag('messages', 'Chat messages')
|
||||
.addTag('import', 'Data import')
|
||||
.build();
|
||||
|
||||
const document = SwaggerModule.createDocument(app, config);
|
||||
SwaggerModule.setup('api/docs', app, document);
|
||||
|
||||
// Also serve raw JSON for client generation
|
||||
writeFileSync('./openapi-spec.json', JSON.stringify(document, null, 2));
|
||||
```
|
||||
|
||||
### Frontend Client Generation
|
||||
|
||||
```bash
|
||||
# Generate TypeScript client
|
||||
npx openapi-generator-cli generate \
|
||||
-i ./openapi-spec.json \
|
||||
-g typescript-fetch \
|
||||
-o ./apps/frontend/src/api/generated \
|
||||
--additional-properties=supportsES6=true,npmName=dreamchat-api
|
||||
|
||||
# Or use Orval for React Query hooks
|
||||
npx orval --config ./orval.config.js
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
| Endpoint | Limit |
|
||||
|----------|-------|
|
||||
| Auth endpoints | 10 req/min |
|
||||
| General API | 100 req/min |
|
||||
| File upload | 5 req/min |
|
||||
| WebSocket messages | 60 msg/min |
|
||||
| LLM streaming | 20 requests/min |
|
||||
|
||||
```typescript
|
||||
// Rate limit headers
|
||||
X-RateLimit-Limit: 100
|
||||
X-RateLimit-Remaining: 95
|
||||
X-RateLimit-Reset: 1645603200
|
||||
```
|
||||
490
doc/architecture.md
Normal file
490
doc/architecture.md
Normal file
@@ -0,0 +1,490 @@
|
||||
# DreamChat System Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
DreamChat is a character simulation platform built with a modular, extensible architecture. The system follows clean architecture principles with clear separation of concerns.
|
||||
|
||||
## High-Level Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Client Layer │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
|
||||
│ │ React │ │ Vite │ │ WebSocket │ │ OpenAPI Generator │ │
|
||||
│ │ (UI) │ │ (Build) │ │ Client │ │ (API Client) │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ API Gateway Layer │
|
||||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ NestJS Backend │ │
|
||||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ Auth │ │ Guards │ │ Validation │ │ WebSocket │ │ │
|
||||
│ │ │ Module │ │ (JWT/Keycloak)│ │ Pipes │ │ Gateway │ │ │
|
||||
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌──────────────────┼──────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐
|
||||
│ Domain Modules │ │ Service Layer │ │ Infrastructure │
|
||||
│ ┌────────────────┐ │ │ ┌────────────────┐ │ │ ┌────────────────┐ │
|
||||
│ │ Character │ │ │ │ LLM Service │ │ │ │ LangChain │ │
|
||||
│ │ Module │ │ │ │ (OpenRouter) │ │ │ │ Integration │ │
|
||||
│ └────────────────┘ │ │ └────────────────┘ │ │ └────────────────┘ │
|
||||
│ ┌────────────────┐ │ │ ┌────────────────┐ │ │ ┌────────────────┐ │
|
||||
│ │ Chat Module │ │ │ │ Memory Service │ │ │ │ Vector Store │ │
|
||||
│ │ (MVP Focus) │ │ │ │ (Vector DB) │ │ │ │ (pgvector) │ │
|
||||
│ └────────────────┘ │ │ └────────────────┘ │ │ └────────────────┘ │
|
||||
│ ┌────────────────┐ │ │ ┌────────────────┐ │ │ ┌────────────────┐ │
|
||||
│ │ Story Module │ │ │ │ Import Service │ │ │ │ Puppeteer │ │
|
||||
│ │ (Phase 2) │ │ │ │ (Adapter) │ │ │ │ (Scraper) │ │
|
||||
│ └────────────────┘ │ │ └────────────────┘ │ │ └────────────────┘ │
|
||||
│ ┌────────────────┐ │ │ ┌────────────────┐ │ │ ┌────────────────┐ │
|
||||
│ │ Multi-Char │ │ │ │ File Processor │ │ │ │ PDF Parser │ │
|
||||
│ │ (Phase 3) │ │ │ │ Service │ │ │ │ MD Parser │ │
|
||||
│ └────────────────┘ │ │ └────────────────┘ │ │ └────────────────┘ │
|
||||
└──────────────────────┘ └──────────────────────┘ └──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ Data Layer │
|
||||
│ ┌─────────────┐ ┌─────────────────────┐ ┌─────────────────────────────┐ │
|
||||
│ │ PostgreSQL │ │ pgvector Extension │ │ Keycloak (External) │ │
|
||||
│ │ (Primary) │ │ (Vector Store) │ │ (Auth Provider) │ │
|
||||
│ └─────────────┘ └─────────────────────┘ └─────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Module Dependencies
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Application Module │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
|
||||
│ │ Auth │ │ User │ │ Config │ │
|
||||
│ │ Module │──│ Module │ │ (Global) │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────┼─────────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌───────────────┐ ┌───────────────┐ ┌───────────────────┐
|
||||
│ Character │ │ Chat │ │ Import/Export │
|
||||
│ Module │ │ Module │ │ Module │
|
||||
│ │ │ (MVP Focus) │ │ │
|
||||
│ • Attributes │ │ │ │ • File Adapter │
|
||||
│ • Personality│ │ • Messages │ │ • Web Adapter │
|
||||
│ • Backstory │ │ • WebSocket │ │ • Preprocessing │
|
||||
└───────────────┘ └───────────────┘ └───────────────────┘
|
||||
│
|
||||
┌───────────────┴───────────────┐
|
||||
▼ ▼
|
||||
┌───────────────────┐ ┌───────────────────┐
|
||||
│ Story Module │ │ Multi-Char Module│
|
||||
│ (Phase 2) │ │ (Phase 3) │
|
||||
│ │ │ │
|
||||
│ • Branching Tree │ │ • Group Chat │
|
||||
│ • Open-ended Gen │ │ • Char-to-Char │
|
||||
│ • Tree View API │ │ • Address Direct │
|
||||
└─────────────────────┘ └───────────────────┘
|
||||
```
|
||||
|
||||
## Component Details
|
||||
|
||||
### Backend (NestJS)
|
||||
|
||||
#### 1. Auth Module
|
||||
```typescript
|
||||
// Dual authentication strategy
|
||||
- KeycloakStrategy (OAuth2/OIDC)
|
||||
- LocalStrategy (Password-based)
|
||||
- JWT Guard for stateless auth
|
||||
- Roles: USER, ADMIN
|
||||
|
||||
// Prisma User model
|
||||
- id, email, username
|
||||
- passwordHash, keycloakSub
|
||||
- role, isActive
|
||||
```
|
||||
|
||||
#### 2. Character Module
|
||||
```typescript
|
||||
- CharacterController (REST)
|
||||
- CharacterService (Business Logic)
|
||||
- CharacterRepository (Prisma)
|
||||
- DTOs: CreateCharacterDto, UpdateCharacterDto, CharacterResponseDto
|
||||
|
||||
Entities:
|
||||
- Character
|
||||
- id, name, avatar
|
||||
- personalityPrompt: string
|
||||
- attributes: JSON (complex attribute system)
|
||||
- backstory: string
|
||||
- createdBy: User
|
||||
- createdAt, updatedAt
|
||||
```
|
||||
|
||||
#### 3. Chat Module (MVP)
|
||||
```typescript
|
||||
- ChatGateway (WebSocket)
|
||||
- ChatService
|
||||
- MessageService
|
||||
- ConversationRepository (Prisma)
|
||||
|
||||
Prisma Models:
|
||||
- Conversation
|
||||
- id, title
|
||||
- characterId (relation)
|
||||
- userId (relation)
|
||||
- messages: Message[]
|
||||
- messageCount, totalTokens
|
||||
- createdAt, updatedAt
|
||||
|
||||
- Message
|
||||
- id, role (MessageRole enum: user | assistant | system)
|
||||
- content: String
|
||||
- tokensUsed: Int?
|
||||
- model: String?
|
||||
- metadata: Json?
|
||||
- conversationId (relation)
|
||||
- createdAt: DateTime
|
||||
|
||||
WebSocket Events:
|
||||
- client:send_message → server:receive_message → llm:generate → server:stream_response → client:receive_chunk
|
||||
```
|
||||
|
||||
#### 4. Memory Service (LangChain + pgvector + Local Embeddings)
|
||||
```typescript
|
||||
- EmbeddingService (Adapter Pattern)
|
||||
- generateEmbeddings(texts: string[]): Promise<number[][]>
|
||||
- getDimension(): number
|
||||
|
||||
Implementations:
|
||||
- LocalEmbeddingProvider: Loads HuggingFace model via @xenova/transformers
|
||||
- HuggingFaceAPIProvider: Uses HuggingFace Inference API
|
||||
|
||||
- VectorStoreService (uses Prisma with pgvector extension)
|
||||
- addDocument(conversationId, content, metadata)
|
||||
- similaritySearch(conversationId, query, k=5)
|
||||
- Uses raw Prisma queries with pgvector operators
|
||||
|
||||
- MemoryManager
|
||||
- buildContext(conversationId, currentMessage): string
|
||||
- summarizeOldMessages(conversationId): Promise<void>
|
||||
- retrieveRelevantMemories(conversationId, query): Document[]
|
||||
|
||||
Prisma Model:
|
||||
- VectorMemory
|
||||
- id
|
||||
- conversationId (relation)
|
||||
- content: String
|
||||
- embedding: Unsupported("vector") // pgvector type
|
||||
- metadata: Json?
|
||||
- createdAt: DateTime
|
||||
```
|
||||
|
||||
#### 5. LLM Service (Adapter Pattern)
|
||||
```typescript
|
||||
interface LLMProvider {
|
||||
generate(messages: Message[]): Promise<string>;
|
||||
stream(messages: Message[]): AsyncIterable<string>;
|
||||
getTokenCount(text: string): number;
|
||||
}
|
||||
|
||||
class OpenRouterProvider implements LLMProvider { ... }
|
||||
class OpenAIProvider implements LLMProvider { ... }
|
||||
class OllamaProvider implements LLMProvider { ... }
|
||||
|
||||
// Configuration via environment
|
||||
LLM_PROVIDER=openrouter
|
||||
LLM_MODEL=openai/gpt-4o
|
||||
LLM_API_KEY=...
|
||||
```
|
||||
|
||||
#### 6. Import Module (Adapter Pattern)
|
||||
```typescript
|
||||
interface ImportAdapter {
|
||||
canHandle(source: ImportSource): boolean;
|
||||
import(source: ImportSource): Promise<Document[]>;
|
||||
}
|
||||
|
||||
// File Adapters
|
||||
class TextFileAdapter implements ImportAdapter { ... }
|
||||
class PdfFileAdapter implements ImportAdapter { ... }
|
||||
class MarkdownFileAdapter implements ImportAdapter { ... }
|
||||
|
||||
// Web Adapters (Predefined scrapers)
|
||||
abstract class WebScraperAdapter implements ImportAdapter {
|
||||
protected abstract canHandleUrl(url: string): boolean;
|
||||
protected abstract extractContent(page: Page): Promise<string>;
|
||||
}
|
||||
|
||||
class AO3Scraper extends WebScraperAdapter { ... }
|
||||
class FanfictionNetScraper extends WebScraperAdapter { ... }
|
||||
// Each scraper validates URL pattern before processing
|
||||
// Uses Puppeteer for headless browser
|
||||
|
||||
// Data Preprocessing Pipeline
|
||||
class DataPreprocessor {
|
||||
clean(text: string): string;
|
||||
chunk(text: string, maxChunkSize: number): string[];
|
||||
extractEntities(text: string): Entity[];
|
||||
}
|
||||
```
|
||||
|
||||
### Frontend (React + Vite)
|
||||
|
||||
#### Component Hierarchy
|
||||
```
|
||||
App
|
||||
├── AuthProvider (Keycloak + Local)
|
||||
├── Router
|
||||
│ ├── /login
|
||||
│ │ └── LoginPage
|
||||
│ │ ├── KeycloakLoginButton
|
||||
│ │ └── PasswordLoginForm
|
||||
│ ├── /characters
|
||||
│ │ └── CharacterListPage
|
||||
│ │ ├── CharacterCard[]
|
||||
│ │ └── CreateCharacterButton
|
||||
│ ├── /characters/:id
|
||||
│ │ └── CharacterDetailPage
|
||||
│ │ ├── CharacterAttributesEditor
|
||||
│ │ ├── PersonalityPromptEditor
|
||||
│ │ └── ChatHistory (if any)
|
||||
│ ├── /chat/:conversationId (MVP Focus)
|
||||
│ │ └── ChatPage
|
||||
│ │ ├── ChatHeader (character info)
|
||||
│ │ ├── MessageList
|
||||
│ │ │ └── MessageBubble[]
|
||||
│ │ └── ChatInput
|
||||
│ │ └── MessageComposer
|
||||
│ ├── /stories (Phase 2)
|
||||
│ │ └── StoryListPage
|
||||
│ │ └── StoryTreeView
|
||||
│ └── /import
|
||||
│ └── ImportPage
|
||||
│ ├── FileUpload (Drag & Drop)
|
||||
│ │ └── FileDropzone
|
||||
│ ├── UrlInput
|
||||
│ │ └── ScraperSelector
|
||||
│ └── ProcessingProgress
|
||||
└── Layout
|
||||
├── Sidebar
|
||||
└── Header
|
||||
```
|
||||
|
||||
#### State Management
|
||||
```typescript
|
||||
// Using Zustand or React Query
|
||||
- authStore: AuthState
|
||||
- characterStore: Character[]
|
||||
- chatStore:
|
||||
- currentConversation: Conversation
|
||||
- messages: Message[]
|
||||
- isStreaming: boolean
|
||||
- wsConnection: WebSocket
|
||||
- importStore: ImportJob[]
|
||||
```
|
||||
|
||||
#### API Client Generation
|
||||
```bash
|
||||
# Generated from OpenAPI spec
|
||||
npx openapi-generator-cli generate \
|
||||
-i http://localhost:3000/api-json \
|
||||
-g typescript-fetch \
|
||||
-o src/api/generated
|
||||
```
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Chat Flow (MVP)
|
||||
```
|
||||
┌─────────┐ ┌──────────┐ ┌────────────┐ ┌─────────────┐
|
||||
│ User │────▶│ Frontend │────▶│ WebSocket │────▶│ Chat │
|
||||
│ │ │ │ │ Gateway │ │ Gateway │
|
||||
└─────────┘ └──────────┘ └────────────┘ └──────┬──────┘
|
||||
│
|
||||
┌────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ ChatService │
|
||||
│ 1. Save user message to DB │
|
||||
│ 2. Call MemoryManager.buildContext() │
|
||||
│ 3. Retrieve relevant memories (vector search) │
|
||||
│ 4. Build system prompt + context + user message │
|
||||
│ 5. Call LLMService.generateStream() │
|
||||
└────────────────────────┬───────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ LLMService │
|
||||
│ 1. Select provider (OpenRouter) │
|
||||
│ 2. Format messages for provider │
|
||||
│ 3. Stream response chunks │
|
||||
│ 4. Return async iterator │
|
||||
└────────────────────────┬───────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ Stream Response │
|
||||
│ 1. Send chunks via WebSocket │
|
||||
│ 2. Accumulate full response │
|
||||
│ 3. Save assistant message to DB │
|
||||
│ 4. Store in vector memory │
|
||||
└────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### File Import Flow
|
||||
```
|
||||
┌──────────┐ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
||||
│ User │────▶│ Frontend │────▶│ POST /api │────▶│ Import │
|
||||
│ Upload │ │ FileSelect │ │ /import/file│ │ Controller│
|
||||
└──────────┘ └─────────────┘ └──────────────┘ └──────┬──────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ImportService │
|
||||
│ 1. Validate file (type, size < 50MB) │
|
||||
│ 2. Select adapter based on mime-type │
|
||||
│ 3. Parse file to raw text │
|
||||
│ 4. Run DataPreprocessor.clean() │
|
||||
│ 5. Chunk into segments │
|
||||
│ 6. Store in import_documents table │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Web Scraping Flow
|
||||
```
|
||||
┌──────────┐ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
||||
│ User │────▶│ Frontend │────▶│ POST /api │────▶│ Import │
|
||||
│ Enter URL│ │ URL Input │ │ /import/url │ │ Controller│
|
||||
└──────────┘ └─────────────┘ └──────────────┘ └──────┬──────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ WebImportService │
|
||||
│ 1. Validate URL format │
|
||||
│ 2. Find matching scraper (or reject) │
|
||||
│ 3. Launch Puppeteer, navigate to URL │
|
||||
│ 4. Extract content using scraper selectors │
|
||||
│ 5. Run DataPreprocessor.clean() │
|
||||
│ 6. Chunk and store │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Directory Structure (pnpm Monorepo)
|
||||
|
||||
```
|
||||
dreamchat/
|
||||
├── apps/
|
||||
│ ├── backend/
|
||||
│ │ ├── src/
|
||||
│ │ │ ├── app.module.ts
|
||||
│ │ │ ├── main.ts
|
||||
│ │ │ ├── config/
|
||||
│ │ │ ├── common/
|
||||
│ │ │ ├── modules/
|
||||
│ │ │ │ ├── auth/
|
||||
│ │ │ │ ├── users/
|
||||
│ │ │ │ ├── characters/
|
||||
│ │ │ │ ├── chat/
|
||||
│ │ │ │ ├── import/
|
||||
│ │ │ │ ├── story/
|
||||
│ │ │ │ └── multi-character/
|
||||
│ │ │ └── shared/
|
||||
│ │ │ ├── services/
|
||||
│ │ │ └── prisma/
|
||||
│ │ ├── test/
|
||||
│ │ ├── Dockerfile
|
||||
│ │ └── package.json
|
||||
│ │
|
||||
│ └── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── main.tsx
|
||||
│ │ ├── App.tsx
|
||||
│ │ ├── api/
|
||||
│ │ ├── components/
|
||||
│ │ ├── pages/
|
||||
│ │ ├── stores/
|
||||
│ │ ├── hooks/
|
||||
│ │ └── utils/
|
||||
│ ├── public/
|
||||
│ ├── Dockerfile
|
||||
│ └── package.json
|
||||
│
|
||||
├── packages/
|
||||
│ ├── shared/ # Shared types & WebSocket definitions
|
||||
│ │ ├── src/
|
||||
│ │ │ ├── websocket/
|
||||
│ │ │ │ ├── events.ts # WebSocket event types
|
||||
│ │ │ │ ├── messages.ts
|
||||
│ │ │ │ └── index.ts
|
||||
│ │ │ ├── api/
|
||||
│ │ │ │ ├── dto.ts # Shared DTOs
|
||||
│ │ │ │ └── index.ts
|
||||
│ │ │ └── index.ts
|
||||
│ │ ├── package.json
|
||||
│ │ └── tsconfig.json
|
||||
│ │
|
||||
│ └── config/ # Shared configurations
|
||||
│ ├── eslint/
|
||||
│ └── typescript/
|
||||
│
|
||||
├── prisma/ # Database schema (shared)
|
||||
│ ├── schema.prisma
|
||||
│ ├── migrations/
|
||||
│ └── seed.ts
|
||||
│
|
||||
├── docker-compose.yml
|
||||
├── pnpm-workspace.yaml
|
||||
├── package.json # Root package.json
|
||||
├── .npmrc
|
||||
├── .devcontainer/
|
||||
└── doc/
|
||||
```
|
||||
|
||||
### Package Management
|
||||
|
||||
```yaml
|
||||
# pnpm-workspace.yaml
|
||||
packages:
|
||||
- 'apps/*'
|
||||
- 'packages/*'
|
||||
```
|
||||
|
||||
```bash
|
||||
# Install all dependencies
|
||||
pnpm install
|
||||
|
||||
# Add dependency to specific app
|
||||
pnpm --filter @dreamchat/backend add @nestjs/jwt
|
||||
|
||||
# Add shared package to apps
|
||||
pnpm --filter @dreamchat/backend add @dreamchat/shared@workspace:*
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Authentication**: JWT tokens with refresh strategy
|
||||
2. **Authorization**: Role-based access control (RBAC)
|
||||
3. **File Upload**:
|
||||
- Size limit: 50MB
|
||||
- Mime-type validation
|
||||
- Storage outside web root
|
||||
4. **Web Scraping**:
|
||||
- URL whitelist (predefined scrapers only)
|
||||
- Rate limiting per domain
|
||||
- Content sanitization
|
||||
5. **WebSocket**:
|
||||
- Auth token validation on connection
|
||||
- Message rate limiting per user
|
||||
6. **Database**:
|
||||
- Prepared statements (Prisma)
|
||||
- Connection pooling
|
||||
709
doc/database-schema.md
Normal file
709
doc/database-schema.md
Normal file
@@ -0,0 +1,709 @@
|
||||
# DreamChat Database Schema
|
||||
|
||||
## Overview
|
||||
|
||||
PostgreSQL with pgvector extension for vector storage. All data is stored locally (offline-first).
|
||||
|
||||
## Extensions Required
|
||||
|
||||
```sql
|
||||
-- Enable required extensions
|
||||
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
|
||||
CREATE EXTENSION IF NOT EXISTS "pgvector";
|
||||
```
|
||||
|
||||
## Entity Relationship Diagram
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ users │ │ characters │ │ conversations │
|
||||
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
|
||||
│ id (PK) │◄──────│ user_id (FK) │ │ id (PK) │
|
||||
│ email │ │ id (PK) │◄──────│ character_id(FK)│
|
||||
│ username │ │ name │ │ user_id (FK) │
|
||||
│ password_hash │ │ avatar_url │ │ title │
|
||||
│ keycloak_sub │ │ personality │ │ created_at │
|
||||
│ role │ │ backstory │ │ updated_at │
|
||||
│ created_at │ │ attributes │ └────────┬────────┘
|
||||
│ updated_at │ │ created_at │ │
|
||||
└─────────────────┘ │ updated_at │ │
|
||||
└─────────────────┘ │
|
||||
┌─────────────────┐ │
|
||||
│import_documents │ │
|
||||
├─────────────────┤ │
|
||||
│ id (PK) │ │
|
||||
│ user_id (FK) │ │
|
||||
│ source_type │ ┌─────────────────┐ │
|
||||
│ source_name │ │ messages │◄───────────────┘
|
||||
│ content │ ├─────────────────┤
|
||||
│ metadata │ │ id (PK) │
|
||||
│ vector_id │ │ conversation_id │
|
||||
│ created_at │ │ role │
|
||||
└─────────────────┘ │ content │
|
||||
│ tokens_used │
|
||||
│ model │
|
||||
┌─────────────────┐ │ metadata │
|
||||
│vector_memories │ │ created_at │
|
||||
├─────────────────┤ └─────────────────┘
|
||||
│ id (PK) │
|
||||
│ conversation_id │ ┌─────────────────┐
|
||||
│ content │ │ story_branches │ (Phase 2)
|
||||
│ embedding │ ├─────────────────┤
|
||||
│ metadata │ │ id (PK) │
|
||||
│ created_at │ │ conversation_id │
|
||||
└─────────────────┘ │ parent_id (FK) │
|
||||
│ content │
|
||||
│ direction │
|
||||
│ metadata │
|
||||
│ created_at │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
## Table Definitions
|
||||
|
||||
### 1. users
|
||||
|
||||
Stores user account information. Supports both Keycloak (OIDC) and local password authentication.
|
||||
|
||||
```sql
|
||||
CREATE TABLE users (
|
||||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||
email VARCHAR(255) UNIQUE NOT NULL,
|
||||
username VARCHAR(100) UNIQUE NOT NULL,
|
||||
password_hash VARCHAR(255), -- NULL if using Keycloak
|
||||
keycloak_sub VARCHAR(255) UNIQUE, -- NULL if using password auth
|
||||
role VARCHAR(20) DEFAULT 'USER' CHECK (role IN ('USER', 'ADMIN')),
|
||||
is_active BOOLEAN DEFAULT true,
|
||||
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
||||
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
||||
|
||||
-- At least one auth method must be set
|
||||
CONSTRAINT auth_method_check CHECK (
|
||||
(password_hash IS NOT NULL) OR (keycloak_sub IS NOT NULL)
|
||||
)
|
||||
);
|
||||
|
||||
CREATE INDEX idx_users_email ON users(email);
|
||||
CREATE INDEX idx_users_keycloak_sub ON users(keycloak_sub);
|
||||
```
|
||||
|
||||
### 2. characters
|
||||
|
||||
Character definitions with complex attribute system (JSONB for flexibility).
|
||||
|
||||
```sql
|
||||
CREATE TABLE characters (
|
||||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
avatar_url TEXT,
|
||||
|
||||
-- Core personality prompt sent to LLM
|
||||
personality_prompt TEXT NOT NULL,
|
||||
|
||||
-- Backstory context for the character
|
||||
backstory TEXT,
|
||||
|
||||
-- Complex attribute system (structured JSON)
|
||||
-- Example: {"traits": ["brave", "witty"], "age": 25, "species": "human"}
|
||||
attributes JSONB DEFAULT '{}',
|
||||
|
||||
-- Character configuration
|
||||
config JSONB DEFAULT '{
|
||||
"model": "openai/gpt-4o",
|
||||
"temperature": 0.7,
|
||||
"max_tokens": 2048,
|
||||
"memory_enabled": true
|
||||
}',
|
||||
|
||||
is_public BOOLEAN DEFAULT false,
|
||||
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
||||
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_characters_user_id ON characters(user_id);
|
||||
CREATE INDEX idx_characters_name ON characters(name);
|
||||
CREATE INDEX idx_characters_attributes ON characters USING GIN(attributes);
|
||||
```
|
||||
|
||||
### 3. conversations
|
||||
|
||||
Chat sessions between user and character.
|
||||
|
||||
```sql
|
||||
CREATE TABLE conversations (
|
||||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
character_id UUID NOT NULL REFERENCES characters(id) ON DELETE CASCADE,
|
||||
title VARCHAR(255), -- Auto-generated or user-defined
|
||||
|
||||
-- Context window management
|
||||
message_count INTEGER DEFAULT 0,
|
||||
total_tokens INTEGER DEFAULT 0,
|
||||
|
||||
-- Conversation settings
|
||||
settings JSONB DEFAULT '{}',
|
||||
|
||||
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
||||
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_conversations_user_id ON conversations(user_id);
|
||||
CREATE INDEX idx_conversations_character_id ON conversations(character_id);
|
||||
CREATE INDEX idx_conversations_created_at ON conversations(created_at);
|
||||
```
|
||||
|
||||
### 4. messages
|
||||
|
||||
Individual chat messages.
|
||||
|
||||
```sql
|
||||
CREATE TYPE message_role AS ENUM ('user', 'assistant', 'system');
|
||||
|
||||
CREATE TABLE messages (
|
||||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||
conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
|
||||
role message_role NOT NULL,
|
||||
content TEXT NOT NULL,
|
||||
|
||||
-- LLM metadata
|
||||
tokens_used INTEGER,
|
||||
model VARCHAR(100),
|
||||
|
||||
-- Additional metadata (temperature, latency, etc.)
|
||||
metadata JSONB DEFAULT '{}',
|
||||
|
||||
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_messages_conversation_id ON messages(conversation_id);
|
||||
CREATE INDEX idx_messages_created_at ON messages(created_at);
|
||||
CREATE INDEX idx_messages_conversation_created ON messages(conversation_id, created_at);
|
||||
```
|
||||
|
||||
### 5. vector_memories
|
||||
|
||||
Vector embeddings for conversation memory using pgvector. Stores chunked content for semantic search.
|
||||
|
||||
```sql
|
||||
-- Create vector extension first
|
||||
CREATE EXTENSION IF NOT EXISTS vector;
|
||||
|
||||
CREATE TABLE vector_memories (
|
||||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||
conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
|
||||
|
||||
-- The text content
|
||||
content TEXT NOT NULL,
|
||||
|
||||
-- Vector embedding (configurable dimension based on model)
|
||||
-- Common sizes: 384 (all-MiniLM-L6-v2), 768 (all-mpnet-base-v2), 1024 (BGE)
|
||||
-- Must match the EMBEDDING_DIMENSION env var
|
||||
embedding VECTOR({{EMBEDDING_DIMENSION}}),
|
||||
|
||||
-- Metadata for filtering
|
||||
metadata JSONB DEFAULT '{
|
||||
"chunk_index": 0,
|
||||
"source": "conversation",
|
||||
"timestamp": null
|
||||
}',
|
||||
|
||||
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
|
||||
);
|
||||
|
||||
-- HNSW index for efficient similarity search
|
||||
-- Note: Index is created after table creation based on actual dimension
|
||||
-- CREATE INDEX idx_vector_memories_embedding ON vector_memories
|
||||
-- USING hnsw (embedding vector_cosine_ops);
|
||||
|
||||
CREATE INDEX idx_vector_memories_conversation ON vector_memories(conversation_id);
|
||||
```
|
||||
|
||||
### 6. import_documents
|
||||
|
||||
Raw imported documents from files or web scraping.
|
||||
|
||||
```sql
|
||||
CREATE TYPE import_source_type AS ENUM ('file', 'url');
|
||||
CREATE TYPE import_status AS ENUM ('pending', 'processing', 'completed', 'failed');
|
||||
|
||||
CREATE TABLE import_documents (
|
||||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
|
||||
source_type import_source_type NOT NULL,
|
||||
source_name VARCHAR(255) NOT NULL, -- filename or URL
|
||||
|
||||
-- Mime type for files
|
||||
mime_type VARCHAR(100),
|
||||
|
||||
-- File size in bytes
|
||||
file_size BIGINT,
|
||||
|
||||
-- Raw content (preprocessed)
|
||||
content TEXT,
|
||||
|
||||
-- Processing status
|
||||
status import_status DEFAULT 'pending',
|
||||
error_message TEXT,
|
||||
|
||||
-- Metadata (source info, extraction method, etc.)
|
||||
metadata JSONB DEFAULT '{}',
|
||||
|
||||
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
||||
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_import_documents_user_id ON import_documents(user_id);
|
||||
CREATE INDEX idx_import_documents_status ON import_documents(status);
|
||||
```
|
||||
|
||||
### 7. story_branches (Phase 2)
|
||||
|
||||
Tree structure for branching narratives.
|
||||
|
||||
```sql
|
||||
CREATE TABLE story_branches (
|
||||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||
conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
|
||||
|
||||
-- Self-referential for tree structure
|
||||
parent_id UUID REFERENCES story_branches(id) ON DELETE CASCADE,
|
||||
|
||||
-- Branch content
|
||||
title VARCHAR(255),
|
||||
content TEXT NOT NULL, -- The generated story content
|
||||
|
||||
-- User direction that led to this branch
|
||||
user_direction TEXT,
|
||||
|
||||
-- Branch metadata
|
||||
generation_params JSONB DEFAULT '{}',
|
||||
|
||||
-- Tree position
|
||||
depth INTEGER DEFAULT 0,
|
||||
branch_order INTEGER DEFAULT 0,
|
||||
|
||||
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_story_branches_conversation ON story_branches(conversation_id);
|
||||
CREATE INDEX idx_story_branches_parent ON story_branches(parent_id);
|
||||
```
|
||||
|
||||
### 8. conversation_participants (Phase 3 - Multi-Character)
|
||||
|
||||
Supports multiple characters in a single conversation.
|
||||
|
||||
```sql
|
||||
CREATE TABLE conversation_participants (
|
||||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||||
conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
|
||||
character_id UUID NOT NULL REFERENCES characters(id) ON DELETE CASCADE,
|
||||
|
||||
-- Participant settings
|
||||
is_active BOOLEAN DEFAULT true,
|
||||
auto_respond BOOLEAN DEFAULT true, -- Auto-generate responses
|
||||
|
||||
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
||||
|
||||
UNIQUE(conversation_id, character_id)
|
||||
);
|
||||
|
||||
CREATE INDEX idx_participants_conversation ON conversation_participants(conversation_id);
|
||||
```
|
||||
|
||||
## Prisma Schema (Reference)
|
||||
|
||||
### Full Schema Definition
|
||||
|
||||
```prisma
|
||||
// schema.prisma
|
||||
|
||||
generator client {
|
||||
provider = "prisma-client-js"
|
||||
}
|
||||
|
||||
datasource db {
|
||||
provider = "postgresql"
|
||||
url = env("DATABASE_URL")
|
||||
}
|
||||
|
||||
// Enums
|
||||
enum UserRole {
|
||||
USER
|
||||
ADMIN
|
||||
}
|
||||
|
||||
enum MessageRole {
|
||||
user
|
||||
assistant
|
||||
system
|
||||
}
|
||||
|
||||
enum ImportSourceType {
|
||||
file
|
||||
url
|
||||
}
|
||||
|
||||
enum ImportStatus {
|
||||
pending
|
||||
processing
|
||||
completed
|
||||
failed
|
||||
}
|
||||
|
||||
// Models
|
||||
model User {
|
||||
id String @id @default(uuid())
|
||||
email String @unique
|
||||
username String @unique
|
||||
passwordHash String?
|
||||
keycloakSub String? @unique
|
||||
role UserRole @default(USER)
|
||||
isActive Boolean @default(true)
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
|
||||
characters Character[]
|
||||
conversations Conversation[]
|
||||
importDocs ImportDocument[]
|
||||
|
||||
@@index([email])
|
||||
@@index([keycloakSub])
|
||||
}
|
||||
|
||||
model Character {
|
||||
id String @id @default(uuid())
|
||||
name String
|
||||
avatarUrl String?
|
||||
personalityPrompt String
|
||||
backstory String?
|
||||
attributes Json @default("{}")
|
||||
config Json @default("{}")
|
||||
isPublic Boolean @default(false)
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
|
||||
userId String
|
||||
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
|
||||
conversations Conversation[]
|
||||
|
||||
@@index([userId])
|
||||
@@index([name])
|
||||
}
|
||||
|
||||
model Conversation {
|
||||
id String @id @default(uuid())
|
||||
title String?
|
||||
messageCount Int @default(0)
|
||||
totalTokens Int @default(0)
|
||||
settings Json @default("{}")
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
|
||||
userId String
|
||||
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
|
||||
characterId String
|
||||
character Character @relation(fields: [characterId], references: [id], onDelete: Cascade)
|
||||
messages Message[]
|
||||
vectorMemories VectorMemory[]
|
||||
storyBranches StoryBranch[]
|
||||
participants ConversationParticipant[]
|
||||
|
||||
@@index([userId])
|
||||
@@index([characterId])
|
||||
@@index([createdAt])
|
||||
}
|
||||
|
||||
model Message {
|
||||
id String @id @default(uuid())
|
||||
role MessageRole
|
||||
content String
|
||||
tokensUsed Int?
|
||||
model String?
|
||||
metadata Json?
|
||||
createdAt DateTime @default(now())
|
||||
|
||||
conversationId String
|
||||
conversation Conversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
|
||||
|
||||
@@index([conversationId])
|
||||
@@index([createdAt])
|
||||
@@index([conversationId, createdAt])
|
||||
}
|
||||
|
||||
model VectorMemory {
|
||||
id String @id @default(uuid())
|
||||
content String
|
||||
embedding Unsupported("vector")? // pgvector extension
|
||||
metadata Json?
|
||||
createdAt DateTime @default(now())
|
||||
|
||||
conversationId String
|
||||
conversation Conversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
|
||||
|
||||
@@index([conversationId])
|
||||
}
|
||||
|
||||
model ImportDocument {
|
||||
id String @id @default(uuid())
|
||||
sourceType ImportSourceType
|
||||
sourceName String
|
||||
mimeType String?
|
||||
fileSize BigInt?
|
||||
content String?
|
||||
status ImportStatus @default(pending)
|
||||
errorMessage String?
|
||||
metadata Json?
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
|
||||
userId String
|
||||
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
|
||||
|
||||
@@index([userId])
|
||||
@@index([status])
|
||||
}
|
||||
|
||||
model StoryBranch {
|
||||
id String @id @default(uuid())
|
||||
title String?
|
||||
content String
|
||||
userDirection String
|
||||
generationParams Json?
|
||||
depth Int @default(0)
|
||||
branchOrder Int @default(0)
|
||||
createdAt DateTime @default(now())
|
||||
|
||||
conversationId String
|
||||
conversation Conversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
|
||||
parentId String?
|
||||
parent StoryBranch? @relation("BranchTree", fields: [parentId], references: [id], onDelete: Cascade)
|
||||
children StoryBranch[] @relation("BranchTree")
|
||||
|
||||
@@index([conversationId])
|
||||
@@index([parentId])
|
||||
}
|
||||
|
||||
model ConversationParticipant {
|
||||
id String @id @default(uuid())
|
||||
isActive Boolean @default(true)
|
||||
autoRespond Boolean @default(true)
|
||||
createdAt DateTime @default(now())
|
||||
|
||||
conversationId String
|
||||
conversation Conversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
|
||||
characterId String
|
||||
|
||||
@@unique([conversationId, characterId])
|
||||
@@index([conversationId])
|
||||
}
|
||||
```
|
||||
|
||||
### Prisma Client Usage Examples
|
||||
|
||||
```typescript
|
||||
// src/shared/prisma/prisma.service.ts
|
||||
import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
|
||||
import { PrismaClient } from '@prisma/client';
|
||||
|
||||
@Injectable()
|
||||
export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
|
||||
async onModuleInit() {
|
||||
await this.$connect();
|
||||
}
|
||||
|
||||
async onModuleDestroy() {
|
||||
await this.$disconnect();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// Repository pattern with Prisma
|
||||
@Injectable()
|
||||
export class CharacterRepository {
|
||||
constructor(private prisma: PrismaService) {}
|
||||
|
||||
async findByUser(userId: string) {
|
||||
return this.prisma.character.findMany({
|
||||
where: { userId },
|
||||
orderBy: { updatedAt: 'desc' },
|
||||
});
|
||||
}
|
||||
|
||||
async create(data: CreateCharacterDto, userId: string) {
|
||||
return this.prisma.character.create({
|
||||
data: { ...data, userId },
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Vector Memory Query with Prisma
|
||||
|
||||
```typescript
|
||||
// Similarity search using pgvector with Prisma
|
||||
async similaritySearch(
|
||||
conversationId: string,
|
||||
queryEmbedding: number[],
|
||||
k: number = 5
|
||||
) {
|
||||
// Using raw query for pgvector-specific operations
|
||||
const results = await this.prisma.$queryRaw`
|
||||
SELECT
|
||||
id,
|
||||
content,
|
||||
metadata,
|
||||
embedding <=> ${queryEmbedding}::vector as distance
|
||||
FROM "VectorMemory"
|
||||
WHERE "conversationId" = ${conversationId}
|
||||
ORDER BY embedding <=> ${queryEmbedding}::vector
|
||||
LIMIT ${k}
|
||||
`;
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
// Alternative: using cosine similarity
|
||||
async similaritySearchCosine(
|
||||
conversationId: string,
|
||||
queryEmbedding: number[],
|
||||
k: number = 5
|
||||
) {
|
||||
const results = await this.prisma.$queryRaw`
|
||||
SELECT
|
||||
id,
|
||||
content,
|
||||
metadata,
|
||||
1 - (embedding <=> ${queryEmbedding}::vector) as similarity
|
||||
FROM "VectorMemory"
|
||||
WHERE "conversationId" = ${conversationId}
|
||||
ORDER BY similarity DESC
|
||||
LIMIT ${k}
|
||||
`;
|
||||
|
||||
return results;
|
||||
}
|
||||
```
|
||||
|
||||
### Embedding Configuration
|
||||
|
||||
```typescript
|
||||
// Configuration for embedding providers
|
||||
interface EmbeddingConfig {
|
||||
provider: 'local' | 'huggingface-api';
|
||||
model: string;
|
||||
dimension: number;
|
||||
// For local provider
|
||||
localModelPath?: string;
|
||||
// For HuggingFace API
|
||||
apiKey?: string;
|
||||
apiEndpoint?: string;
|
||||
}
|
||||
|
||||
// Example configurations:
|
||||
// Local: { provider: 'local', model: 'Xenova/all-MiniLM-L6-v2', dimension: 384 }
|
||||
// HF API: { provider: 'huggingface-api', model: 'sentence-transformers/all-mpnet-base-v2', dimension: 768 }
|
||||
```
|
||||
|
||||
## Prisma Migration Strategy
|
||||
|
||||
### Initial Migration
|
||||
|
||||
```bash
|
||||
# 1. Initialize Prisma
|
||||
npx prisma init
|
||||
|
||||
# 2. Define schema in prisma/schema.prisma
|
||||
|
||||
# 3. Create first migration
|
||||
npx prisma migrate dev --name init
|
||||
|
||||
# 4. Generate Prisma Client
|
||||
npx prisma generate
|
||||
```
|
||||
|
||||
### Migration Workflow
|
||||
|
||||
```bash
|
||||
# After schema changes
|
||||
npx prisma migrate dev --name descriptive_name
|
||||
|
||||
# Production deployment
|
||||
npx prisma migrate deploy
|
||||
|
||||
# Generate client (in CI/CD)
|
||||
npx prisma generate
|
||||
```
|
||||
|
||||
### Migration File Example
|
||||
|
||||
```sql
|
||||
-- migrations/20240223120000_init/migration.sql
|
||||
|
||||
-- Enable extensions
|
||||
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
|
||||
CREATE EXTENSION IF NOT EXISTS "vector";
|
||||
|
||||
-- CreateEnum
|
||||
CREATE TYPE "UserRole" AS ENUM ('USER', 'ADMIN');
|
||||
|
||||
-- CreateEnum
|
||||
CREATE TYPE "MessageRole" AS ENUM ('user', 'assistant', 'system');
|
||||
|
||||
-- CreateTable
|
||||
CREATE TABLE "User" (
|
||||
"id" UUID NOT NULL DEFAULT uuid_generate_v4(),
|
||||
"email" TEXT NOT NULL,
|
||||
"username" TEXT NOT NULL,
|
||||
-- ... etc
|
||||
);
|
||||
|
||||
-- CreateIndex
|
||||
CREATE UNIQUE INDEX "User_email_key" ON "User"("email");
|
||||
|
||||
-- Vector index (HNSW) - created manually after migration
|
||||
CREATE INDEX idx_vector_memories_embedding ON "VectorMemory"
|
||||
USING hnsw (embedding vector_cosine_ops);
|
||||
```
|
||||
|
||||
### Seeding
|
||||
|
||||
```typescript
|
||||
// prisma/seed.ts
|
||||
import { PrismaClient } from '@prisma/client';
|
||||
|
||||
const prisma = new PrismaClient();
|
||||
|
||||
async function main() {
|
||||
// Seed default admin or test data
|
||||
await prisma.user.create({
|
||||
data: {
|
||||
email: 'admin@dreamchat.local',
|
||||
username: 'admin',
|
||||
role: 'ADMIN',
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
main()
|
||||
.catch(console.error)
|
||||
.finally(() => prisma.$disconnect());
|
||||
```
|
||||
|
||||
```bash
|
||||
# Run seed
|
||||
npx prisma db seed
|
||||
```
|
||||
|
||||
## Backup Strategy
|
||||
|
||||
```bash
|
||||
# pg_dump with custom format
|
||||
docker exec dreamchat-postgres pg_dump -U postgres -Fc dreamchat > backup.dump
|
||||
|
||||
# Restore
|
||||
pg_restore -U postgres -d dreamchat backup.dump
|
||||
```
|
||||
725
doc/deployment.md
Normal file
725
doc/deployment.md
Normal file
@@ -0,0 +1,725 @@
|
||||
# DreamChat Deployment Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This document covers the deployment configuration including Docker Compose setup, DevContainer configuration, and production deployment procedures.
|
||||
|
||||
## DevContainer Setup
|
||||
|
||||
### .devcontainer/devcontainer.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "DreamChat Development",
|
||||
"dockerComposeFile": "docker-compose.yml",
|
||||
"service": "app",
|
||||
"workspaceFolder": "/workspace",
|
||||
"features": {
|
||||
"ghcr.io/devcontainers/features/node:1": {
|
||||
"version": "20"
|
||||
},
|
||||
"ghcr.io/devcontainers/features/docker-in-docker:2": {}
|
||||
},
|
||||
"customizations": {
|
||||
"vscode": {
|
||||
"extensions": [
|
||||
"dbaeumer.vscode-eslint",
|
||||
"esbenp.prettier-vscode",
|
||||
"bradlc.vscode-tailwindcss",
|
||||
"ms-vscode.vscode-typescript-next",
|
||||
"nestjs.vscode-nestjs",
|
||||
"prisma.prisma"
|
||||
],
|
||||
"settings": {
|
||||
"editor.formatOnSave": true,
|
||||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||||
"typescript.preferences.importModuleSpecifier": "relative"
|
||||
}
|
||||
}
|
||||
},
|
||||
"forwardPorts": [3000, 5173, 5432, 8080],
|
||||
"portsAttributes": {
|
||||
"3000": {
|
||||
"label": "Backend API",
|
||||
"onAutoForward": "notify"
|
||||
},
|
||||
"5173": {
|
||||
"label": "Frontend Dev Server",
|
||||
"onAutoForward": "notify"
|
||||
},
|
||||
"5432": {
|
||||
"label": "PostgreSQL",
|
||||
"onAutoForward": "silent"
|
||||
},
|
||||
"8080": {
|
||||
"label": "Keycloak",
|
||||
"onAutoForward": "notify"
|
||||
}
|
||||
},
|
||||
"postCreateCommand": "bash .devcontainer/post-create.sh",
|
||||
"remoteUser": "node",
|
||||
"mounts": [
|
||||
"source=${localWorkspaceFolderBasename}-node_modules,target=${containerWorkspaceFolder}/node_modules,type=volume",
|
||||
"source=${localWorkspaceFolderBasename}-pnpm-store,target=/home/node/.local/share/pnpm/store,type=volume"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### .devcontainer/docker-compose.yml
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
app:
|
||||
build:
|
||||
context: ..
|
||||
dockerfile: .devcontainer/Dockerfile
|
||||
volumes:
|
||||
- ..:/workspace:cached
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
command: sleep infinity
|
||||
environment:
|
||||
- DATABASE_URL=postgresql://postgres:postgres@db:5432/dreamchat
|
||||
- REDIS_URL=redis://redis:6379
|
||||
- KEYCLOAK_URL=http://keycloak:8080
|
||||
depends_on:
|
||||
- db
|
||||
- redis
|
||||
- keycloak
|
||||
networks:
|
||||
- dreamchat-network
|
||||
|
||||
db:
|
||||
image: ankane/pgvector:latest
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
POSTGRES_USER: postgres
|
||||
POSTGRES_PASSWORD: postgres
|
||||
POSTGRES_DB: dreamchat
|
||||
volumes:
|
||||
- postgres-data:/var/lib/postgresql/data
|
||||
ports:
|
||||
- "5432:5432"
|
||||
networks:
|
||||
- dreamchat-network
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "6379:6379"
|
||||
networks:
|
||||
- dreamchat-network
|
||||
|
||||
keycloak:
|
||||
image: quay.io/keycloak/keycloak:23.0
|
||||
restart: unless-stopped
|
||||
command: start-dev
|
||||
environment:
|
||||
KEYCLOAK_ADMIN: admin
|
||||
KEYCLOAK_ADMIN_PASSWORD: admin
|
||||
KC_DB: postgres
|
||||
KC_DB_URL: jdbc:postgresql://db:5432/keycloak
|
||||
KC_DB_USERNAME: postgres
|
||||
KC_DB_PASSWORD: postgres
|
||||
ports:
|
||||
- "8080:8080"
|
||||
depends_on:
|
||||
- db
|
||||
networks:
|
||||
- dreamchat-network
|
||||
|
||||
volumes:
|
||||
postgres-data:
|
||||
|
||||
networks:
|
||||
dreamchat-network:
|
||||
driver: bridge
|
||||
```
|
||||
|
||||
### .devcontainer/Dockerfile
|
||||
|
||||
```dockerfile
|
||||
FROM mcr.microsoft.com/devcontainers/typescript-node:20
|
||||
|
||||
# Install additional tools
|
||||
RUN apt-get update && apt-get install -y \
|
||||
postgresql-client \
|
||||
redis-tools \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Install pnpm
|
||||
RUN npm install -g pnpm@8
|
||||
|
||||
# Set working directory
|
||||
WORKDIR /workspace
|
||||
|
||||
# Install global packages
|
||||
RUN npm install -g @nestjs/cli@latest
|
||||
|
||||
# Create non-root user
|
||||
USER node
|
||||
```
|
||||
|
||||
### .devcontainer/post-create.sh
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "🚀 Setting up DreamChat monorepo development environment..."
|
||||
|
||||
# Install pnpm globally
|
||||
npm install -g pnpm@8
|
||||
|
||||
# Install all dependencies (uses pnpm workspaces)
|
||||
echo "📦 Installing dependencies..."
|
||||
cd /workspace
|
||||
pnpm install
|
||||
|
||||
# Build shared packages first
|
||||
echo "📦 Building shared packages..."
|
||||
pnpm --filter @dreamchat/shared build
|
||||
|
||||
# Generate Prisma client
|
||||
pnpm db:generate
|
||||
|
||||
# Copy environment files if they don't exist
|
||||
if [ ! -f /workspace/apps/backend/.env ]; then
|
||||
echo "⚙️ Creating backend .env file..."
|
||||
cat > /workspace/apps/backend/.env << EOF
|
||||
NODE_ENV=development
|
||||
PORT=3000
|
||||
DATABASE_URL=postgresql://postgres:postgres@db:5432/dreamchat
|
||||
JWT_SECRET=dev-jwt-secret-change-in-production
|
||||
JWT_EXPIRES_IN=1h
|
||||
JWT_REFRESH_EXPIRES_IN=7d
|
||||
LLM_PROVIDER=openrouter
|
||||
LLM_API_KEY=your-openrouter-api-key
|
||||
LLM_MODEL=openai/gpt-4o
|
||||
KEYCLOAK_URL=http://localhost:8080
|
||||
KEYCLOAK_REALM=dreamchat
|
||||
KEYCLOAK_CLIENT_ID=dreamchat-backend
|
||||
EOF
|
||||
fi
|
||||
|
||||
if [ ! -f /workspace/apps/frontend/.env ]; then
|
||||
echo "⚙️ Creating frontend .env file..."
|
||||
cat > /workspace/apps/frontend/.env << EOF
|
||||
VITE_API_URL=http://localhost:3000/api
|
||||
VITE_WS_URL=ws://localhost:3000
|
||||
VITE_KEYCLOAK_URL=http://localhost:8080
|
||||
VITE_KEYCLOAK_REALM=dreamchat
|
||||
VITE_KEYCLOAK_CLIENT_ID=dreamchat-frontend
|
||||
EOF
|
||||
fi
|
||||
|
||||
echo "✅ Development environment setup complete!"
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo "1. Start all apps: pnpm dev"
|
||||
echo "2. Or start individually:"
|
||||
echo " - Backend: pnpm --filter @dreamchat/backend dev"
|
||||
echo " - Frontend: pnpm --filter @dreamchat/frontend dev"
|
||||
echo "3. Access Keycloak admin at http://localhost:8080 (admin/admin)"
|
||||
```
|
||||
|
||||
## Docker Compose Production
|
||||
|
||||
### docker-compose.yml (Root)
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
# Backend API
|
||||
backend:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: apps/backend/Dockerfile
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- NODE_ENV=production
|
||||
- PORT=3000
|
||||
- DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@db:5432/dreamchat
|
||||
- JWT_SECRET=${JWT_SECRET}
|
||||
- JWT_EXPIRES_IN=${JWT_EXPIRES_IN:-1h}
|
||||
- JWT_REFRESH_EXPIRES_IN=${JWT_REFRESH_EXPIRES_IN:-7d}
|
||||
- LLM_PROVIDER=${LLM_PROVIDER}
|
||||
- LLM_API_KEY=${LLM_API_KEY}
|
||||
- LLM_MODEL=${LLM_MODEL}
|
||||
- EMBEDDING_PROVIDER=${EMBEDDING_PROVIDER:-local}
|
||||
- EMBEDDING_MODEL=${EMBEDDING_MODEL:-Xenova/all-MiniLM-L6-v2}
|
||||
- EMBEDDING_DIMENSION=${EMBEDDING_DIMENSION:-384}
|
||||
- EMBEDDING_DEVICE=${EMBEDDING_DEVICE:-cpu}
|
||||
- HUGGINGFACE_API_KEY=${HUGGINGFACE_API_KEY}
|
||||
- KEYCLOAK_URL=${KEYCLOAK_URL}
|
||||
- KEYCLOAK_REALM=${KEYCLOAK_REALM}
|
||||
- KEYCLOAK_CLIENT_ID=${KEYCLOAK_CLIENT_ID}
|
||||
- KEYCLOAK_CLIENT_SECRET=${KEYCLOAK_CLIENT_SECRET}
|
||||
ports:
|
||||
- "3000:3000"
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
volumes:
|
||||
- backend-logs:/app/logs
|
||||
- model-cache:/app/models
|
||||
networks:
|
||||
- dreamchat-network
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:3000/health"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
|
||||
# Frontend
|
||||
frontend:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: apps/frontend/Dockerfile
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
environment:
|
||||
- VITE_API_URL=/api
|
||||
- VITE_WS_URL=/ws
|
||||
depends_on:
|
||||
- backend
|
||||
networks:
|
||||
- dreamchat-network
|
||||
|
||||
# Database
|
||||
db:
|
||||
image: ankane/pgvector:latest
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
POSTGRES_USER: postgres
|
||||
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
|
||||
POSTGRES_DB: dreamchat
|
||||
volumes:
|
||||
- postgres-data:/var/lib/postgresql/data
|
||||
- ./init-scripts:/docker-entrypoint-initdb.d
|
||||
networks:
|
||||
- dreamchat-network
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U postgres"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
# Redis (optional, for session storage and caching)
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
- redis-data:/data
|
||||
networks:
|
||||
- dreamchat-network
|
||||
|
||||
# Nginx Reverse Proxy (optional)
|
||||
nginx:
|
||||
image: nginx:alpine
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
volumes:
|
||||
- ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
|
||||
- ./nginx/ssl:/etc/nginx/ssl:ro
|
||||
- model-cache:/model-cache:ro
|
||||
depends_on:
|
||||
- backend
|
||||
- frontend
|
||||
networks:
|
||||
- dreamchat-network
|
||||
|
||||
volumes:
|
||||
postgres-data:
|
||||
redis-data:
|
||||
backend-logs:
|
||||
model-cache: # Persist downloaded embedding models
|
||||
|
||||
networks:
|
||||
dreamchat-network:
|
||||
driver: bridge
|
||||
```
|
||||
|
||||
### Embedding Model Cache (Optional)
|
||||
|
||||
To avoid re-downloading models on every restart, models are cached in a Docker volume:
|
||||
|
||||
```yaml
|
||||
# Add to docker-compose volumes
|
||||
volumes:
|
||||
model-cache:
|
||||
```
|
||||
|
||||
Models are downloaded on first use and cached at `/app/models` in the backend container.
|
||||
|
||||
Common models and their sizes:
|
||||
- `Xenova/all-MiniLM-L6-v2`: ~80MB (384 dimensions)
|
||||
- `Xenova/all-mpnet-base-v2`: ~420MB (768 dimensions)
|
||||
- `BAAI/bge-small-en`: ~130MB (384 dimensions)
|
||||
|
||||
### .env.example
|
||||
|
||||
```bash
|
||||
# Database
|
||||
POSTGRES_PASSWORD=your_secure_password_here
|
||||
|
||||
# JWT
|
||||
JWT_SECRET=your_jwt_secret_key_min_32_chars
|
||||
JWT_EXPIRES_IN=1h
|
||||
JWT_REFRESH_EXPIRES_IN=7d
|
||||
|
||||
# LLM Configuration
|
||||
LLM_PROVIDER=openrouter
|
||||
LLM_API_KEY=sk-or-v1-...
|
||||
LLM_MODEL=openai/gpt-4o
|
||||
|
||||
# Embedding Configuration (Local HuggingFace by default)
|
||||
EMBEDDING_PROVIDER=local
|
||||
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2
|
||||
EMBEDDING_DIMENSION=384
|
||||
EMBEDDING_DEVICE=cpu
|
||||
|
||||
# HuggingFace API (optional - if not using local embeddings)
|
||||
# HUGGINGFACE_API_KEY=hf_...
|
||||
|
||||
# Keycloak (optional - for external auth)
|
||||
KEYCLOAK_URL=http://keycloak:8080
|
||||
KEYCLOAK_REALM=dreamchat
|
||||
KEYCLOAK_CLIENT_ID=dreamchat-backend
|
||||
KEYCLOAK_CLIENT_SECRET=your_keycloak_secret
|
||||
```
|
||||
|
||||
## Backend Dockerfile
|
||||
|
||||
```dockerfile
|
||||
# apps/backend/Dockerfile
|
||||
FROM node:20-alpine AS base
|
||||
RUN npm install -g pnpm@8
|
||||
|
||||
FROM base AS dependencies
|
||||
WORKDIR /app
|
||||
|
||||
# Copy workspace configuration
|
||||
COPY pnpm-workspace.yaml package.json ./
|
||||
COPY apps/backend/package.json ./apps/backend/
|
||||
COPY packages/shared/package.json ./packages/shared/
|
||||
|
||||
# Install dependencies
|
||||
RUN pnpm install --frozen-lockfile
|
||||
|
||||
FROM base AS build
|
||||
WORKDIR /app
|
||||
COPY --from=dependencies /app/node_modules ./node_modules
|
||||
COPY --from=dependencies /app/apps/backend/node_modules ./apps/backend/node_modules
|
||||
COPY --from=dependencies /app/packages/shared/node_modules ./packages/shared/node_modules
|
||||
|
||||
# Copy source code
|
||||
COPY packages/shared ./packages/shared
|
||||
COPY apps/backend ./apps/backend
|
||||
|
||||
# Build shared packages first
|
||||
RUN pnpm --filter @dreamchat/shared build
|
||||
|
||||
# Build backend
|
||||
RUN pnpm --filter @dreamchat/backend build
|
||||
|
||||
FROM base AS production
|
||||
WORKDIR /app
|
||||
|
||||
# Copy only production dependencies
|
||||
COPY --from=dependencies /app/node_modules ./node_modules
|
||||
COPY --from=dependencies /app/apps/backend/node_modules ./apps/backend/node_modules
|
||||
COPY --from=build /app/apps/backend/dist ./dist
|
||||
COPY --from=build /app/packages/shared/dist ./node_modules/@dreamchat/shared/dist
|
||||
|
||||
# Create logs directory
|
||||
RUN mkdir -p /app/logs
|
||||
|
||||
# Non-root user
|
||||
RUN addgroup -g 1001 -S nodejs
|
||||
RUN adduser -S nodejs -u 1001
|
||||
USER nodejs
|
||||
|
||||
EXPOSE 3000
|
||||
|
||||
CMD ["node", "dist/main.js"]
|
||||
```
|
||||
|
||||
## Frontend Dockerfile
|
||||
|
||||
```dockerfile
|
||||
# apps/frontend/Dockerfile
|
||||
FROM node:20-alpine AS base
|
||||
RUN npm install -g pnpm@8
|
||||
|
||||
FROM base AS dependencies
|
||||
WORKDIR /app
|
||||
|
||||
# Copy workspace configuration
|
||||
COPY pnpm-workspace.yaml package.json ./
|
||||
COPY apps/frontend/package.json ./apps/frontend/
|
||||
COPY packages/shared/package.json ./packages/shared/
|
||||
|
||||
# Install dependencies
|
||||
RUN pnpm install --frozen-lockfile
|
||||
|
||||
FROM base AS build
|
||||
WORKDIR /app
|
||||
COPY --from=dependencies /app/node_modules ./node_modules
|
||||
COPY --from=dependencies /app/apps/frontend/node_modules ./apps/frontend/node_modules
|
||||
COPY --from=dependencies /app/packages/shared/node_modules ./packages/shared/node_modules
|
||||
|
||||
# Copy source code
|
||||
COPY packages/shared ./packages/shared
|
||||
COPY apps/frontend ./apps/frontend
|
||||
|
||||
# Build shared packages first
|
||||
RUN pnpm --filter @dreamchat/shared build
|
||||
|
||||
# Build frontend
|
||||
RUN pnpm --filter @dreamchat/frontend build
|
||||
|
||||
# Production with Nginx
|
||||
FROM nginx:alpine
|
||||
|
||||
# Copy built assets
|
||||
COPY --from=build /app/apps/frontend/dist /usr/share/nginx/html
|
||||
|
||||
# Copy nginx config
|
||||
COPY apps/frontend/nginx.conf /etc/nginx/conf.d/default.conf
|
||||
|
||||
EXPOSE 80
|
||||
|
||||
CMD ["nginx", "-g", "daemon off;"]
|
||||
```
|
||||
|
||||
### frontend/nginx.conf
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name localhost;
|
||||
root /usr/share/nginx/html;
|
||||
index index.html;
|
||||
|
||||
# Gzip compression
|
||||
gzip on;
|
||||
gzip_vary on;
|
||||
gzip_min_length 1024;
|
||||
gzip_types text/plain text/css text/xml text/javascript application/json application/javascript application/xml+rss application/rss+xml font/truetype font/opentype application/vnd.ms-fontobject image/svg+xml;
|
||||
|
||||
# API proxy
|
||||
location /api {
|
||||
proxy_pass http://backend:3000/api;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection 'upgrade';
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_cache_bypass $http_upgrade;
|
||||
}
|
||||
|
||||
# WebSocket proxy
|
||||
location /ws {
|
||||
proxy_pass http://backend:3000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
|
||||
# Static files
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
add_header Cache-Control "public, max-age=31536000, immutable";
|
||||
}
|
||||
|
||||
# Health check
|
||||
location /health {
|
||||
access_log off;
|
||||
return 200 "healthy\n";
|
||||
add_header Content-Type text/plain;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Keycloak Configuration
|
||||
|
||||
### Initial Setup
|
||||
|
||||
1. Access Keycloak admin console: `http://localhost:8080/admin`
|
||||
2. Login with admin credentials
|
||||
3. Create new realm: `dreamchat`
|
||||
4. Create client: `dreamchat-backend`
|
||||
- Client authentication: ON
|
||||
- Authorization: ON
|
||||
- Valid redirect URIs: `http://localhost:3000/*`
|
||||
- Web origins: `http://localhost:3000`
|
||||
|
||||
5. Create client: `dreamchat-frontend`
|
||||
- Client authentication: OFF
|
||||
- Valid redirect URIs: `http://localhost:5173/*`
|
||||
- Web origins: `http://localhost:5173`
|
||||
|
||||
### realm-export.json (Optional)
|
||||
|
||||
```json
|
||||
{
|
||||
"realm": "dreamchat",
|
||||
"enabled": true,
|
||||
"clients": [
|
||||
{
|
||||
"clientId": "dreamchat-backend",
|
||||
"enabled": true,
|
||||
"clientAuthenticatorType": "client-secret",
|
||||
"secret": "**********",
|
||||
"redirectUris": ["http://localhost:3000/*"],
|
||||
"webOrigins": ["http://localhost:3000"],
|
||||
"protocol": "openid-connect"
|
||||
},
|
||||
{
|
||||
"clientId": "dreamchat-frontend",
|
||||
"enabled": true,
|
||||
"publicClient": true,
|
||||
"redirectUris": ["http://localhost:5173/*"],
|
||||
"webOrigins": ["http://localhost:5173"],
|
||||
"protocol": "openid-connect"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Deployment Procedures
|
||||
|
||||
### Local Development
|
||||
|
||||
```bash
|
||||
# Using DevContainer
|
||||
1. Open project in VS Code
|
||||
2. Click "Reopen in Container"
|
||||
3. Wait for setup to complete
|
||||
4. Start services:
|
||||
- Terminal 1: pnpm --filter @dreamchat/backend dev
|
||||
- Terminal 2: pnpm --filter @dreamchat/frontend dev
|
||||
- Or run all: pnpm dev
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
|
||||
```bash
|
||||
# 1. Clone repository
|
||||
git clone https://github.com/yourusername/dreamchat.git
|
||||
cd dreamchat
|
||||
|
||||
# 2. Create environment file
|
||||
cp .env.example .env
|
||||
# Edit .env with production values
|
||||
|
||||
# 3. Build and start
|
||||
docker-compose up -d --build
|
||||
|
||||
# 4. Run database migrations
|
||||
docker-compose exec backend pnpm db:migrate
|
||||
|
||||
# 5. Check health
|
||||
curl http://localhost:3000/health
|
||||
|
||||
# 6. View logs
|
||||
docker-compose logs -f backend
|
||||
```
|
||||
|
||||
### Backup and Restore
|
||||
|
||||
```bash
|
||||
# Backup database
|
||||
docker-compose exec db pg_dump -U postgres -Fc dreamchat > backup_$(date +%Y%m%d).dump
|
||||
|
||||
# Restore database
|
||||
docker-compose exec -T db pg_restore -U postgres -d dreamchat < backup_20240223.dump
|
||||
|
||||
# Backup volumes
|
||||
docker run --rm -v dreamchat_postgres-data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-backup.tar.gz -C /data .
|
||||
```
|
||||
|
||||
### Updates
|
||||
|
||||
```bash
|
||||
# Pull latest changes
|
||||
git pull origin main
|
||||
|
||||
# Rebuild and restart
|
||||
docker-compose down
|
||||
docker-compose up -d --build
|
||||
|
||||
# Run migrations
|
||||
docker-compose exec backend npx prisma migrate deploy
|
||||
```
|
||||
|
||||
## Monitoring and Logging
|
||||
|
||||
### Health Checks
|
||||
|
||||
```bash
|
||||
# Backend health
|
||||
curl http://localhost:3000/health
|
||||
|
||||
# Database health
|
||||
docker-compose exec db pg_isready -U postgres
|
||||
|
||||
# Full stack
|
||||
docker-compose ps
|
||||
```
|
||||
|
||||
### Log Management
|
||||
|
||||
```bash
|
||||
# View all logs
|
||||
docker-compose logs
|
||||
|
||||
# View specific service
|
||||
docker-compose logs -f backend
|
||||
|
||||
# View last 100 lines
|
||||
docker-compose logs --tail=100 backend
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Change default passwords** in production
|
||||
2. **Use HTTPS** with valid SSL certificates
|
||||
3. **Enable firewall** rules for required ports only
|
||||
4. **Regular updates** of base images and dependencies
|
||||
5. **Secrets management** - use Docker secrets or external vault
|
||||
6. **Network isolation** - separate networks for different services
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Database connection failed**
|
||||
- Check DATABASE_URL environment variable
|
||||
- Ensure db service is healthy: `docker-compose ps`
|
||||
|
||||
2. **WebSocket not connecting**
|
||||
- Verify VITE_WS_URL matches your domain
|
||||
- Check Nginx proxy configuration
|
||||
|
||||
3. **Keycloak authentication issues**
|
||||
- Verify client configuration in Keycloak admin
|
||||
- Check redirect URIs match exactly
|
||||
|
||||
4. **File upload fails**
|
||||
- Check file size limits in Nginx config
|
||||
- Verify disk space in backend container
|
||||
635
doc/frontend-guide.md
Normal file
635
doc/frontend-guide.md
Normal file
@@ -0,0 +1,635 @@
|
||||
# DreamChat Frontend Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the frontend architecture, component structure, and development guidelines for the DreamChat React application.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Category | Technology | Purpose |
|
||||
|----------|------------|---------|
|
||||
| Framework | React 18+ | UI library |
|
||||
| Build Tool | Vite | Fast development and building |
|
||||
| Language | TypeScript | Type safety |
|
||||
| Styling | Tailwind CSS | Utility-first CSS |
|
||||
| State Management | Zustand | Global state |
|
||||
| Server State | TanStack Query | API data caching |
|
||||
| Routing | React Router v6 | Navigation |
|
||||
| WebSocket | Socket.io-client | Real-time communication |
|
||||
| Shared Types | `@dreamchat/shared` | Monorepo shared package |
|
||||
| API Client | OpenAPI Generator | Auto-generated API client |
|
||||
| Forms | React Hook Form + Zod | Form handling and validation |
|
||||
| UI Components | Radix UI + shadcn/ui | Accessible primitives |
|
||||
| Icons | Lucide React | Icon library |
|
||||
| Testing | Vitest + React Testing Library | Unit/component tests |
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
apps/frontend/
|
||||
├── src/
|
||||
│ ├── api/
|
||||
│ │ ├── generated/ # Auto-generated from OpenAPI
|
||||
│ │ │ ├── models/ # DTO types
|
||||
│ │ │ └── apis/ # API client classes
|
||||
│ │ └── client.ts # Axios/fetch configuration
|
||||
│ │
|
||||
│ ├── websocket/
|
||||
│ │ ├── socket.ts # Socket.io client setup
|
||||
│ │ └── hooks.ts # WebSocket hooks (uses @dreamchat/shared)
|
||||
│ │
|
||||
│ ├── components/
|
||||
│ │ ├── ui/ # Reusable UI components
|
||||
│ │ │ ├── button.tsx
|
||||
│ │ │ ├── input.tsx
|
||||
│ │ │ ├── card.tsx
|
||||
│ │ │ ├── dialog.tsx
|
||||
│ │ │ └── ...
|
||||
│ │ ├── layout/
|
||||
│ │ │ ├── sidebar.tsx
|
||||
│ │ │ ├── header.tsx
|
||||
│ │ │ └── main-layout.tsx
|
||||
│ │ ├── character/
|
||||
│ │ │ ├── character-card.tsx
|
||||
│ │ │ ├── character-form.tsx
|
||||
│ │ │ ├── attribute-editor.tsx
|
||||
│ │ │ └── personality-editor.tsx
|
||||
│ │ ├── chat/
|
||||
│ │ │ ├── chat-container.tsx
|
||||
│ │ │ ├── message-list.tsx
|
||||
│ │ │ ├── message-bubble.tsx
|
||||
│ │ │ ├── chat-input.tsx
|
||||
│ │ │ └── typing-indicator.tsx
|
||||
│ │ └── import/
|
||||
│ │ ├── file-dropzone.tsx
|
||||
│ │ ├── url-input.tsx
|
||||
│ │ └── import-progress.tsx
|
||||
│ │
|
||||
│ ├── pages/
|
||||
│ │ ├── login-page.tsx
|
||||
│ │ ├── register-page.tsx
|
||||
│ │ ├── character-list-page.tsx
|
||||
│ │ ├── character-detail-page.tsx
|
||||
│ │ ├── chat-page.tsx
|
||||
│ │ ├── story-page.tsx
|
||||
│ │ └── import-page.tsx
|
||||
│ │
|
||||
│ ├── hooks/
|
||||
│ │ ├── use-auth.ts
|
||||
│ │ ├── use-chat.ts
|
||||
│ │ ├── use-characters.ts
|
||||
│ │ └── use-import.ts
|
||||
│ │
|
||||
│ ├── stores/
|
||||
│ │ ├── auth-store.ts
|
||||
│ │ ├── chat-store.ts
|
||||
│ │ └── ui-store.ts
|
||||
│ │
|
||||
│ ├── lib/
|
||||
│ │ ├── utils.ts # Utility functions
|
||||
│ │ └── constants.ts # App constants
|
||||
│ │
|
||||
│ ├── types/
|
||||
│ │ └── index.ts # App-specific types
|
||||
│ │
|
||||
│ ├── styles/
|
||||
│ │ └── globals.css
|
||||
│ │
|
||||
│ ├── main.tsx
|
||||
│ └── App.tsx
|
||||
│
|
||||
├── public/
|
||||
│ └── assets/
|
||||
│
|
||||
├── index.html
|
||||
├── vite.config.ts
|
||||
├── tailwind.config.ts
|
||||
├── tsconfig.json
|
||||
└── package.json
|
||||
```
|
||||
|
||||
## Component Architecture
|
||||
|
||||
### UI Components (shadcn/ui pattern)
|
||||
|
||||
Base components built on Radix UI primitives:
|
||||
|
||||
```typescript
|
||||
// components/ui/button.tsx
|
||||
import * as React from "react";
|
||||
import { cva, type VariantProps } from "class-variance-authority";
|
||||
import { cn } from "@/lib/utils";
|
||||
|
||||
const buttonVariants = cva(
|
||||
"inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors",
|
||||
{
|
||||
variants: {
|
||||
variant: {
|
||||
default: "bg-primary text-primary-foreground hover:bg-primary/90",
|
||||
destructive: "bg-destructive text-destructive-foreground",
|
||||
outline: "border border-input bg-background hover:bg-accent",
|
||||
secondary: "bg-secondary text-secondary-foreground",
|
||||
ghost: "hover:bg-accent hover:text-accent-foreground",
|
||||
link: "underline-offset-4 hover:underline text-primary",
|
||||
},
|
||||
size: {
|
||||
default: "h-10 px-4 py-2",
|
||||
sm: "h-9 rounded-md px-3",
|
||||
lg: "h-11 rounded-md px-8",
|
||||
icon: "h-10 w-10",
|
||||
},
|
||||
},
|
||||
defaultVariants: {
|
||||
variant: "default",
|
||||
size: "default",
|
||||
},
|
||||
}
|
||||
);
|
||||
|
||||
export interface ButtonProps
|
||||
extends React.ButtonHTMLAttributes<HTMLButtonElement>,
|
||||
VariantProps<typeof buttonVariants> {}
|
||||
|
||||
const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
|
||||
({ className, variant, size, ...props }, ref) => {
|
||||
return (
|
||||
<button
|
||||
className={cn(buttonVariants({ variant, size, className }))}
|
||||
ref={ref}
|
||||
{...props}
|
||||
/>
|
||||
);
|
||||
}
|
||||
);
|
||||
Button.displayName = "Button";
|
||||
|
||||
export { Button, buttonVariants };
|
||||
```
|
||||
|
||||
### Feature Components
|
||||
|
||||
Character form example:
|
||||
|
||||
```typescript
|
||||
// components/character/character-form.tsx
|
||||
import { useForm } from "react-hook-form";
|
||||
import { zodResolver } from "@hookform/resolvers/zod";
|
||||
import * as z from "zod";
|
||||
import { Button } from "@/components/ui/button";
|
||||
import { Input } from "@/components/ui/input";
|
||||
import { Textarea } from "@/components/ui/textarea";
|
||||
import { AttributeEditor } from "./attribute-editor";
|
||||
|
||||
const characterSchema = z.object({
|
||||
name: z.string().min(1, "Name is required"),
|
||||
personalityPrompt: z.string().min(10, "Personality prompt too short"),
|
||||
backstory: z.string().optional(),
|
||||
attributes: z.record(z.any()).default({}),
|
||||
});
|
||||
|
||||
type CharacterFormData = z.infer<typeof characterSchema>;
|
||||
|
||||
interface CharacterFormProps {
|
||||
initialData?: Partial<CharacterFormData>;
|
||||
onSubmit: (data: CharacterFormData) => Promise<void>;
|
||||
}
|
||||
|
||||
export function CharacterForm({ initialData, onSubmit }: CharacterFormProps) {
|
||||
const form = useForm<CharacterFormData>({
|
||||
resolver: zodResolver(characterSchema),
|
||||
defaultValues: initialData || {
|
||||
name: "",
|
||||
personalityPrompt: "",
|
||||
backstory: "",
|
||||
attributes: {},
|
||||
},
|
||||
});
|
||||
|
||||
return (
|
||||
<form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
|
||||
<div>
|
||||
<label>Name</label>
|
||||
<Input {...form.register("name")} />
|
||||
{form.formState.errors.name && (
|
||||
<span className="text-red-500">{form.formState.errors.name.message}</span>
|
||||
)}
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<label>Personality Prompt</label>
|
||||
<Textarea {...form.register("personalityPrompt")} rows={5} />
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<label>Backstory</label>
|
||||
<Textarea {...form.register("backstory")} rows={5} />
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<label>Attributes</label>
|
||||
<AttributeEditor
|
||||
value={form.watch("attributes")}
|
||||
onChange={(attrs) => form.setValue("attributes", attrs)}
|
||||
/>
|
||||
</div>
|
||||
|
||||
<Button type="submit" disabled={form.formState.isSubmitting}>
|
||||
{initialData ? "Update" : "Create"} Character
|
||||
</Button>
|
||||
</form>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## State Management
|
||||
|
||||
### Zustand Store Example
|
||||
|
||||
```typescript
|
||||
// stores/auth-store.ts
|
||||
import { create } from "zustand";
|
||||
import { persist } from "zustand/middleware";
|
||||
|
||||
interface User {
|
||||
id: string;
|
||||
email: string;
|
||||
username: string;
|
||||
}
|
||||
|
||||
interface AuthState {
|
||||
user: User | null;
|
||||
accessToken: string | null;
|
||||
refreshToken: string | null;
|
||||
isAuthenticated: boolean;
|
||||
setAuth: (user: User, accessToken: string, refreshToken: string) => void;
|
||||
clearAuth: () => void;
|
||||
updateAccessToken: (token: string) => void;
|
||||
}
|
||||
|
||||
export const useAuthStore = create<AuthState>()(
|
||||
persist(
|
||||
(set) => ({
|
||||
user: null,
|
||||
accessToken: null,
|
||||
refreshToken: null,
|
||||
isAuthenticated: false,
|
||||
setAuth: (user, accessToken, refreshToken) =>
|
||||
set({ user, accessToken, refreshToken, isAuthenticated: true }),
|
||||
clearAuth: () =>
|
||||
set({
|
||||
user: null,
|
||||
accessToken: null,
|
||||
refreshToken: null,
|
||||
isAuthenticated: false,
|
||||
}),
|
||||
updateAccessToken: (token) => set({ accessToken: token }),
|
||||
}),
|
||||
{
|
||||
name: "auth-storage",
|
||||
partialize: (state) => ({
|
||||
accessToken: state.accessToken,
|
||||
refreshToken: state.refreshToken,
|
||||
user: state.user,
|
||||
}),
|
||||
}
|
||||
)
|
||||
);
|
||||
```
|
||||
|
||||
### TanStack Query for Server State
|
||||
|
||||
```typescript
|
||||
// hooks/use-characters.ts
|
||||
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
|
||||
import { CharactersApi } from "@/api/generated";
|
||||
|
||||
const charactersApi = new CharactersApi();
|
||||
|
||||
export function useCharacters() {
|
||||
return useQuery({
|
||||
queryKey: ["characters"],
|
||||
queryFn: () => charactersApi.charactersControllerFindAll(),
|
||||
});
|
||||
}
|
||||
|
||||
export function useCreateCharacter() {
|
||||
const queryClient = useQueryClient();
|
||||
|
||||
return useMutation({
|
||||
mutationFn: (data: CreateCharacterDto) =>
|
||||
charactersApi.charactersControllerCreate(data),
|
||||
onSuccess: () => {
|
||||
queryClient.invalidateQueries({ queryKey: ["characters"] });
|
||||
},
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## WebSocket Integration
|
||||
|
||||
Uses shared types from `@dreamchat/shared` for type-safe communication.
|
||||
|
||||
```typescript
|
||||
// src/websocket/socket.ts
|
||||
import { io, Socket } from "socket.io-client";
|
||||
import { useAuthStore } from "@/stores/auth-store";
|
||||
|
||||
let socket: Socket | null = null;
|
||||
|
||||
export function getSocket(): Socket {
|
||||
if (!socket) {
|
||||
const token = useAuthStore.getState().accessToken;
|
||||
|
||||
socket = io(import.meta.env.VITE_WS_URL, {
|
||||
auth: { token },
|
||||
transports: ["websocket"],
|
||||
});
|
||||
|
||||
socket.on("connect", () => {
|
||||
console.log("WebSocket connected");
|
||||
});
|
||||
|
||||
socket.on("disconnect", () => {
|
||||
console.log("WebSocket disconnected");
|
||||
});
|
||||
|
||||
socket.on("ERROR", (error) => {
|
||||
console.error("WebSocket error:", error);
|
||||
});
|
||||
}
|
||||
|
||||
return socket;
|
||||
}
|
||||
|
||||
export function disconnectSocket() {
|
||||
if (socket) {
|
||||
socket.disconnect();
|
||||
socket = null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/websocket/hooks.ts
|
||||
import { useEffect, useCallback } from "react";
|
||||
import { getSocket } from "./socket";
|
||||
import {
|
||||
WebSocketEventType,
|
||||
WebSocketMessage,
|
||||
JoinConversationPayload,
|
||||
SendMessagePayload,
|
||||
StreamChunkPayload,
|
||||
StreamCompletePayload,
|
||||
ErrorPayload,
|
||||
} from "@dreamchat/shared";
|
||||
|
||||
export function useChatSocket(conversationId: string) {
|
||||
const socket = getSocket();
|
||||
|
||||
useEffect(() => {
|
||||
const payload: JoinConversationPayload = { conversationId };
|
||||
socket.emit(WebSocketEventType.JOIN_CONVERSATION, payload);
|
||||
|
||||
return () => {
|
||||
socket.emit(WebSocketEventType.LEAVE_CONVERSATION, { conversationId });
|
||||
};
|
||||
}, [conversationId, socket]);
|
||||
|
||||
const sendMessage = useCallback(
|
||||
(content: string, streaming = true) => {
|
||||
const payload: SendMessagePayload = {
|
||||
conversationId,
|
||||
content,
|
||||
streaming,
|
||||
};
|
||||
socket.emit(WebSocketEventType.SEND_MESSAGE, payload);
|
||||
},
|
||||
[conversationId, socket]
|
||||
);
|
||||
|
||||
const stopGeneration = useCallback(() => {
|
||||
socket.emit(WebSocketEventType.STOP_GENERATION, { conversationId });
|
||||
}, [conversationId, socket]);
|
||||
|
||||
return { sendMessage, stopGeneration };
|
||||
}
|
||||
|
||||
export function useChatEvents(
|
||||
onStreamChunk: (chunk: string) => void,
|
||||
onStreamComplete: (message: StreamCompletePayload) => void,
|
||||
onError: (error: ErrorPayload) => void
|
||||
) {
|
||||
const socket = getSocket();
|
||||
|
||||
useEffect(() => {
|
||||
const handleChunk = (msg: WebSocketMessage<StreamChunkPayload>) => {
|
||||
onStreamChunk(msg.payload.chunk);
|
||||
};
|
||||
|
||||
const handleComplete = (msg: WebSocketMessage<StreamCompletePayload>) => {
|
||||
onStreamComplete(msg.payload);
|
||||
};
|
||||
|
||||
const handleError = (msg: WebSocketMessage<ErrorPayload>) => {
|
||||
onError(msg.payload);
|
||||
};
|
||||
|
||||
socket.on(WebSocketEventType.STREAM_CHUNK, handleChunk);
|
||||
socket.on(WebSocketEventType.STREAM_COMPLETE, handleComplete);
|
||||
socket.on(WebSocketEventType.ERROR, handleError);
|
||||
|
||||
return () => {
|
||||
socket.off(WebSocketEventType.STREAM_CHUNK, handleChunk);
|
||||
socket.off(WebSocketEventType.STREAM_COMPLETE, handleComplete);
|
||||
socket.off(WebSocketEventType.ERROR, handleError);
|
||||
};
|
||||
}, [socket, onStreamChunk, onStreamComplete, onError]);
|
||||
}
|
||||
```
|
||||
|
||||
## Routing
|
||||
|
||||
```typescript
|
||||
// App.tsx
|
||||
import { BrowserRouter, Routes, Route, Navigate } from "react-router-dom";
|
||||
import { useAuthStore } from "@/stores/auth-store";
|
||||
import { MainLayout } from "@/components/layout/main-layout";
|
||||
import { LoginPage } from "@/pages/login-page";
|
||||
import { CharacterListPage } from "@/pages/character-list-page";
|
||||
import { ChatPage } from "@/pages/chat-page";
|
||||
|
||||
function ProtectedRoute({ children }: { children: React.ReactNode }) {
|
||||
const isAuthenticated = useAuthStore((state) => state.isAuthenticated);
|
||||
return isAuthenticated ? <>{children}</> : <Navigate to="/login" />;
|
||||
}
|
||||
|
||||
function App() {
|
||||
return (
|
||||
<BrowserRouter>
|
||||
<Routes>
|
||||
<Route path="/login" element={<LoginPage />} />
|
||||
<Route
|
||||
path="/"
|
||||
element={
|
||||
<ProtectedRoute>
|
||||
<MainLayout />
|
||||
</ProtectedRoute>
|
||||
}
|
||||
>
|
||||
<Route index element={<Navigate to="/characters" />} />
|
||||
<Route path="characters" element={<CharacterListPage />} />
|
||||
<Route path="characters/:id" element={<CharacterDetailPage />} />
|
||||
<Route path="chat/:conversationId" element={<ChatPage />} />
|
||||
<Route path="stories" element={<StoryPage />} />
|
||||
<Route path="import" element={<ImportPage />} />
|
||||
</Route>
|
||||
</Routes>
|
||||
</BrowserRouter>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Styling with Tailwind
|
||||
|
||||
```typescript
|
||||
// tailwind.config.ts
|
||||
import type { Config } from "tailwindcss";
|
||||
|
||||
const config: Config = {
|
||||
darkMode: ["class"],
|
||||
content: ["./src/**/*.{js,ts,jsx,tsx}"],
|
||||
theme: {
|
||||
extend: {
|
||||
colors: {
|
||||
border: "hsl(var(--border))",
|
||||
input: "hsl(var(--input))",
|
||||
ring: "hsl(var(--ring))",
|
||||
background: "hsl(var(--background))",
|
||||
foreground: "hsl(var(--foreground))",
|
||||
primary: {
|
||||
DEFAULT: "hsl(var(--primary))",
|
||||
foreground: "hsl(var(--primary-foreground))",
|
||||
},
|
||||
secondary: {
|
||||
DEFAULT: "hsl(var(--secondary))",
|
||||
foreground: "hsl(var(--secondary-foreground))",
|
||||
},
|
||||
destructive: {
|
||||
DEFAULT: "hsl(var(--destructive))",
|
||||
foreground: "hsl(var(--destructive-foreground))",
|
||||
},
|
||||
muted: {
|
||||
DEFAULT: "hsl(var(--muted))",
|
||||
foreground: "hsl(var(--muted-foreground))",
|
||||
},
|
||||
accent: {
|
||||
DEFAULT: "hsl(var(--accent))",
|
||||
foreground: "hsl(var(--accent-foreground))",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
plugins: [require("tailwindcss-animate")],
|
||||
};
|
||||
|
||||
export default config;
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Component Tests
|
||||
|
||||
```typescript
|
||||
// components/character/__tests__/character-card.test.tsx
|
||||
import { render, screen } from "@testing-library/react";
|
||||
import { CharacterCard } from "../character-card";
|
||||
|
||||
const mockCharacter = {
|
||||
id: "1",
|
||||
name: "Alice",
|
||||
avatarUrl: "https://example.com/avatar.png",
|
||||
personalityPrompt: "A curious explorer",
|
||||
};
|
||||
|
||||
describe("CharacterCard", () => {
|
||||
it("renders character name", () => {
|
||||
render(<CharacterCard character={mockCharacter} />);
|
||||
expect(screen.getByText("Alice")).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it("renders avatar when provided", () => {
|
||||
render(<CharacterCard character={mockCharacter} />);
|
||||
expect(screen.getByAltText("Alice")).toHaveAttribute(
|
||||
"src",
|
||||
"https://example.com/avatar.png"
|
||||
);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Hook Tests
|
||||
|
||||
```typescript
|
||||
// hooks/__tests__/use-auth.test.ts
|
||||
import { renderHook, act } from "@testing-library/react";
|
||||
import { useAuthStore } from "@/stores/auth-store";
|
||||
|
||||
describe("useAuthStore", () => {
|
||||
it("sets authentication state", () => {
|
||||
const { result } = renderHook(() => useAuthStore());
|
||||
|
||||
act(() => {
|
||||
result.current.setAuth(
|
||||
{ id: "1", email: "test@test.com", username: "test" },
|
||||
"access-token",
|
||||
"refresh-token"
|
||||
);
|
||||
});
|
||||
|
||||
expect(result.current.isAuthenticated).toBe(true);
|
||||
expect(result.current.user?.username).toBe("test");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```typescript
|
||||
// apps/frontend/.env
|
||||
VITE_API_URL=http://localhost:3000/api
|
||||
VITE_WS_URL=ws://localhost:3000
|
||||
VITE_KEYCLOAK_URL=http://localhost:8080
|
||||
VITE_KEYCLOAK_REALM=dreamchat
|
||||
VITE_KEYCLOAK_CLIENT_ID=dreamchat-frontend
|
||||
```
|
||||
|
||||
## Build Configuration
|
||||
|
||||
```typescript
|
||||
// vite.config.ts
|
||||
import { defineConfig } from "vite";
|
||||
import react from "@vitejs/plugin-react";
|
||||
import path from "path";
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [react()],
|
||||
resolve: {
|
||||
alias: {
|
||||
"@": path.resolve(__dirname, "./src"),
|
||||
},
|
||||
},
|
||||
server: {
|
||||
port: 5173,
|
||||
proxy: {
|
||||
"/api": {
|
||||
target: "http://localhost:3000",
|
||||
changeOrigin: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
build: {
|
||||
outDir: "dist",
|
||||
sourcemap: true,
|
||||
},
|
||||
});
|
||||
```
|
||||
447
doc/implementation-plan.md
Normal file
447
doc/implementation-plan.md
Normal file
@@ -0,0 +1,447 @@
|
||||
# DreamChat Implementation Plan
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the phased implementation approach for DreamChat.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Project Setup & Infrastructure
|
||||
|
||||
**Timeline**: Week 1
|
||||
|
||||
### Goals
|
||||
- Set up pnpm monorepo structure
|
||||
- Configure development environment with DevContainer
|
||||
- Establish shared packages for WebSocket types
|
||||
- Configure CI/CD pipeline
|
||||
|
||||
### Tasks
|
||||
|
||||
#### Monorepo Setup
|
||||
- [ ] Initialize pnpm workspace
|
||||
- [ ] Create root package.json and pnpm-workspace.yaml
|
||||
- [ ] Set up shared package (`packages/shared`)
|
||||
- [ ] Configure ESLint and Prettier at root
|
||||
- [ ] Set up TypeScript project references
|
||||
|
||||
#### Backend Setup
|
||||
- [ ] Initialize NestJS app in `apps/backend`
|
||||
- [ ] Configure Prisma ORM with PostgreSQL
|
||||
- [ ] Install and configure pgvector extension
|
||||
- [ ] Define Prisma schema for all entities
|
||||
- [ ] Configure Jest for unit testing
|
||||
- [ ] Set up Swagger/OpenAPI
|
||||
- [ ] Implement basic logging (Winston/Pino)
|
||||
|
||||
#### Frontend Setup
|
||||
- [ ] Initialize Vite + React + TypeScript in `apps/frontend`
|
||||
- [ ] Configure Tailwind CSS (or similar)
|
||||
- [ ] Configure React Query / Zustand
|
||||
- [ ] Set up React Router
|
||||
- [ ] Configure testing (Vitest + React Testing Library)
|
||||
- [ ] Link shared package (`pnpm add @dreamchat/shared@workspace:*`)
|
||||
|
||||
#### Infrastructure
|
||||
- [ ] Create DevContainer configuration (supports pnpm monorepo)
|
||||
- [ ] Create Docker Compose for development
|
||||
- [ ] Set up GitHub Actions for CI (pnpm caching)
|
||||
- [ ] Configure pre-commit hooks
|
||||
|
||||
#### Shared Types Package
|
||||
- [ ] Create `packages/shared` structure
|
||||
- [ ] Define WebSocket event types and payloads
|
||||
- [ ] Define shared API DTOs
|
||||
- [ ] Set up build configuration
|
||||
- [ ] Link to apps (`pnpm install` with workspace protocol)
|
||||
|
||||
### Deliverables
|
||||
- [ ] Running development environment via DevContainer
|
||||
- [ ] Database connection established
|
||||
- [ ] Basic "Hello World" API endpoint
|
||||
- [ ] Frontend dev server running
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: MVP - Single Character Chat
|
||||
|
||||
**Timeline**: Weeks 2-5
|
||||
|
||||
### Goals
|
||||
- User authentication (Keycloak + password)
|
||||
- Character CRUD with complex attributes
|
||||
- Real-time chat via WebSocket
|
||||
- Vector-based memory system
|
||||
|
||||
### 1.1 Authentication Module (Week 2)
|
||||
|
||||
#### Backend Tasks
|
||||
- [ ] User Prisma model and repository
|
||||
- [ ] Local authentication strategy (Passport)
|
||||
- [ ] JWT token generation and validation
|
||||
- [ ] Keycloak strategy implementation
|
||||
- [ ] Auth guards and decorators
|
||||
- [ ] Password hashing (bcrypt)
|
||||
|
||||
#### Frontend Tasks
|
||||
- [ ] Login page with dual auth options
|
||||
- [ ] Keycloak integration
|
||||
- [ ] JWT storage and refresh logic
|
||||
- [ ] Protected route wrapper
|
||||
|
||||
#### Testing
|
||||
- [ ] Unit tests: AuthService (100% coverage)
|
||||
- [ ] Unit tests: JwtStrategy, LocalStrategy
|
||||
- [ ] E2E tests: Login flow
|
||||
|
||||
### 1.2 User Management (Week 2)
|
||||
|
||||
#### Backend Tasks
|
||||
- [ ] User CRUD endpoints
|
||||
- [ ] User profile endpoints
|
||||
- [ ] Email/username validation
|
||||
|
||||
#### Frontend Tasks
|
||||
- [ ] Registration page
|
||||
- [ ] Profile management page
|
||||
|
||||
#### Testing
|
||||
- [ ] Unit tests: UserService
|
||||
- [ ] Unit tests: UserController
|
||||
|
||||
### 1.3 Character Module (Week 3)
|
||||
|
||||
#### Backend Tasks
|
||||
- [ ] Character Prisma model with JSON attributes
|
||||
- [ ] Character CRUD endpoints
|
||||
- [ ] Character validation DTOs
|
||||
- [ ] Attribute schema validation (optional)
|
||||
|
||||
#### Frontend Tasks
|
||||
- [ ] Character list page
|
||||
- [ ] Character creation form
|
||||
- [ ] Character detail/editor page
|
||||
- [ ] Complex attributes editor (JSON editor)
|
||||
- [ ] Avatar upload
|
||||
|
||||
#### Testing
|
||||
- [ ] Unit tests: CharacterService
|
||||
- [ ] Unit tests: CharacterController
|
||||
- [ ] Component tests: Character forms
|
||||
|
||||
### 1.4 LLM Integration (Week 3)
|
||||
|
||||
#### Backend Tasks
|
||||
- [ ] LLM Provider interface
|
||||
- [ ] OpenRouter provider implementation
|
||||
- [ ] LLM configuration service
|
||||
- [ ] Token counting utilities
|
||||
- [ ] Error handling and retry logic
|
||||
|
||||
#### Testing
|
||||
- [ ] Unit tests: OpenRouterProvider (mocked)
|
||||
- [ ] Unit tests: LLMService
|
||||
|
||||
### 1.5 Vector Memory System (Week 4)
|
||||
|
||||
#### Backend Tasks
|
||||
- [ ] Embedding service interface
|
||||
- [ ] Local embedding provider (@xenova/transformers)
|
||||
- [ ] Dynamic model loading
|
||||
- [ ] Model caching strategy
|
||||
- [ ] Dimension configuration
|
||||
- [ ] HuggingFace API provider (optional/fallback)
|
||||
- [ ] Vector store service (pgvector)
|
||||
- [ ] LangChain integration
|
||||
- [ ] Document chunking utilities
|
||||
- [ ] Similarity search implementation
|
||||
- [ ] Memory manager service
|
||||
|
||||
#### Environment Configuration
|
||||
```bash
|
||||
# Embedding Configuration
|
||||
EMBEDDING_PROVIDER=local # or 'huggingface-api'
|
||||
EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2
|
||||
EMBEDDING_DIMENSION=384
|
||||
EMBEDDING_DEVICE=cpu # or 'gpu' if available
|
||||
|
||||
# HuggingFace API (if using API instead of local)
|
||||
HUGGINGFACE_API_KEY=hf_...
|
||||
```
|
||||
|
||||
#### Testing
|
||||
- [ ] Unit tests: EmbeddingService
|
||||
- [ ] Unit tests: LocalEmbeddingProvider
|
||||
- [ ] Unit tests: VectorStoreService
|
||||
- [ ] Unit tests: MemoryManager
|
||||
|
||||
### 1.6 Chat Module (Week 4-5)
|
||||
|
||||
#### Backend Tasks
|
||||
- [ ] Conversation & Message Prisma models
|
||||
- [ ] ChatGateway (WebSocket)
|
||||
- [ ] ChatService (business logic)
|
||||
- [ ] Message streaming implementation
|
||||
- [ ] Context building with memory retrieval
|
||||
|
||||
#### Frontend Tasks
|
||||
- [ ] Chat page layout
|
||||
- [ ] Message list component
|
||||
- [ ] Message bubble component
|
||||
- [ ] Chat input with send button
|
||||
- [ ] WebSocket client integration
|
||||
- [ ] Streaming message display
|
||||
- [ ] Conversation sidebar
|
||||
|
||||
#### Testing
|
||||
- [ ] Unit tests: ChatService
|
||||
- [ ] Unit tests: MessageService
|
||||
- [ ] Unit tests: ChatGateway
|
||||
- [ ] Component tests: Chat components
|
||||
- [ ] E2E tests: Full chat flow
|
||||
|
||||
### 1.7 Import Module - MVP (Week 5)
|
||||
|
||||
#### Backend Tasks
|
||||
- [ ] Import adapter interface
|
||||
- [ ] Text file adapter
|
||||
- [ ] File upload endpoint
|
||||
- [ ] Data preprocessor (cleaning)
|
||||
- [ ] Basic text chunking
|
||||
|
||||
#### Frontend Tasks
|
||||
- [ ] Import page
|
||||
- [ ] File upload component (drag & drop)
|
||||
- [ ] Import progress/status
|
||||
|
||||
#### Testing
|
||||
- [ ] Unit tests: File adapters
|
||||
- [ ] Unit tests: DataPreprocessor
|
||||
- [ ] Unit tests: ImportController
|
||||
|
||||
### MVP Deliverables
|
||||
- [ ] Users can register/login (Keycloak or password)
|
||||
- [ ] Users can create/edit characters with complex attributes
|
||||
- [ ] Users can start conversations with characters
|
||||
- [ ] Real-time chat with streaming responses
|
||||
- [ ] Vector-based memory for context
|
||||
- [ ] Text file import for character training data
|
||||
- [ ] Unit tests for all backend services
|
||||
- [ ] Docker Compose for deployment
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Story Generation
|
||||
|
||||
**Timeline**: Weeks 6-8
|
||||
|
||||
### Goals
|
||||
- Branching narrative generation
|
||||
- Tree view visualization
|
||||
- URL-based web scraping for imports
|
||||
|
||||
### 2.1 Story Module Backend (Week 6)
|
||||
|
||||
#### Backend Tasks
|
||||
- [ ] StoryBranch Prisma model (tree structure with self-relation)
|
||||
- [ ] Story generation service
|
||||
- [ ] Branching narrative endpoints
|
||||
- [ ] Open-ended generation mode
|
||||
- [ ] Integration with chat history
|
||||
|
||||
#### Testing
|
||||
- [ ] Unit tests: StoryService
|
||||
- [ ] Unit tests: StoryController
|
||||
|
||||
### 2.2 Story Module Frontend (Week 7)
|
||||
|
||||
#### Frontend Tasks
|
||||
- [ ] Tree view component for branches
|
||||
- [ ] Story generation page
|
||||
- [ ] Branch creation/editing UI
|
||||
- [ ] Direction input for branching
|
||||
- [ ] Story navigation controls
|
||||
|
||||
#### Testing
|
||||
- [ ] Component tests: Tree view
|
||||
- [ ] Component tests: Story page
|
||||
|
||||
### 2.3 Import Module - Web Scraping (Week 8)
|
||||
|
||||
#### Backend Tasks
|
||||
- [ ] Web scraper interface
|
||||
- [ ] Puppeteer/Playwright integration
|
||||
- [ ] Predefined scraper: AO3
|
||||
- [ ] Predefined scraper: FanFiction.net
|
||||
- [ ] URL validation and scraper selection
|
||||
- [ ] URL import endpoint
|
||||
|
||||
#### Frontend Tasks
|
||||
- [ ] URL import component
|
||||
- [ ] Scraper status feedback
|
||||
- [ ] Content preview before import
|
||||
|
||||
#### Testing
|
||||
- [ ] Unit tests: Web scraper adapters
|
||||
- [ ] Integration tests: Scraping (mocked browser)
|
||||
|
||||
### Phase 2 Deliverables
|
||||
- [ ] Branching story generation from conversations
|
||||
- [ ] Tree view for navigating story branches
|
||||
- [ ] User can input direction per branch
|
||||
- [ ] URL import with predefined scrapers
|
||||
- [ ] PDF and Markdown file support
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Multi-Character Group Chat
|
||||
|
||||
**Timeline**: Weeks 9-10
|
||||
|
||||
### Goals
|
||||
- Multiple characters in one conversation
|
||||
- Group chat UI
|
||||
- Character-to-character interactions
|
||||
|
||||
### 3.1 Multi-Character Backend (Week 9)
|
||||
|
||||
#### Backend Tasks
|
||||
- [ ] ConversationParticipant Prisma model
|
||||
- [ ] Multi-character chat service
|
||||
- [ ] Auto-response orchestration
|
||||
- [ ] Character addressing detection (@Character)
|
||||
- [ ] Group context management
|
||||
|
||||
#### Testing
|
||||
- [ ] Unit tests: MultiCharacterService
|
||||
- [ ] Unit tests: Participant management
|
||||
|
||||
### 3.2 Multi-Character Frontend (Week 10)
|
||||
|
||||
#### Frontend Tasks
|
||||
- [ ] Group chat layout
|
||||
- [ ] Participant list sidebar
|
||||
- [ ] Character mention support
|
||||
- [ ] Message attribution (which character)
|
||||
- [ ] Add/remove participants UI
|
||||
|
||||
#### Testing
|
||||
- [ ] Component tests: Group chat
|
||||
- [ ] E2E tests: Multi-character flow
|
||||
|
||||
### Phase 3 Deliverables
|
||||
- [ ] Group chat with multiple characters
|
||||
- [ ] Characters can address each other
|
||||
- [ ] Auto-response per character
|
||||
- [ ] Participant management UI
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Polish & Production
|
||||
|
||||
**Timeline**: Week 11-12
|
||||
|
||||
### Goals
|
||||
- Performance optimization
|
||||
- Security hardening
|
||||
- Documentation
|
||||
- Production deployment
|
||||
|
||||
### 4.1 Performance & Optimization
|
||||
- [ ] Database query optimization
|
||||
- [ ] WebSocket connection pooling
|
||||
- [ ] Frontend code splitting
|
||||
- [ ] Image optimization
|
||||
- [ ] Caching layer (Redis optional)
|
||||
|
||||
### 4.2 Security
|
||||
- [ ] Security audit
|
||||
- [ ] Input sanitization review
|
||||
- [ ] Rate limiting implementation
|
||||
- [ ] CORS configuration
|
||||
- [ ] Helmet.js integration
|
||||
|
||||
### 4.3 Documentation
|
||||
- [ ] API documentation complete
|
||||
- [ ] User guide
|
||||
- [ ] Deployment guide
|
||||
- [ ] Development guide
|
||||
|
||||
### 4.4 Production Setup
|
||||
- [ ] Production Docker Compose
|
||||
- [ ] Environment configuration
|
||||
- [ ] SSL/TLS setup
|
||||
- [ ] Backup scripts
|
||||
- [ ] Monitoring setup (Prometheus/Grafana optional)
|
||||
|
||||
### Phase 4 Deliverables
|
||||
- [ ] Production-ready deployment
|
||||
- [ ] Complete documentation
|
||||
- [ ] Security audit passed
|
||||
- [ ] Performance benchmarks met
|
||||
|
||||
---
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Code Quality Standards
|
||||
- **Backend Unit Test Coverage**: Minimum 80%
|
||||
- **Frontend Component Tests**: Critical paths covered
|
||||
- **Code Reviews**: Required for all PRs
|
||||
- **Linting**: Zero warnings policy
|
||||
- **TypeScript**: Strict mode enabled
|
||||
|
||||
### Git Workflow
|
||||
```
|
||||
main (production)
|
||||
↓
|
||||
develop (integration)
|
||||
↓
|
||||
feature/XXX (feature branches)
|
||||
↓
|
||||
PR → Code Review → Merge
|
||||
```
|
||||
|
||||
### Commit Message Convention
|
||||
```
|
||||
feat: add character creation form
|
||||
fix: resolve WebSocket reconnection issue
|
||||
docs: update API specification
|
||||
test: add unit tests for ChatService
|
||||
refactor: simplify memory retrieval logic
|
||||
```
|
||||
|
||||
### Definition of Done
|
||||
- [ ] Feature implemented
|
||||
- [ ] Unit tests written (backend)
|
||||
- [ ] Component tests written (frontend critical paths)
|
||||
- [ ] Code reviewed and approved
|
||||
- [ ] Documentation updated
|
||||
- [ ] No linting errors
|
||||
- [ ] CI pipeline passing
|
||||
|
||||
---
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Impact | Mitigation |
|
||||
|------|--------|------------|
|
||||
| OpenRouter API changes | High | Adapter pattern allows easy provider switch |
|
||||
| Web scraping site changes | Medium | Scraper versioning, graceful degradation |
|
||||
| Token limits for memory | Medium | Summarization, smart chunking |
|
||||
| WebSocket scaling | Medium | Horizontal scaling with Redis adapter (future) |
|
||||
| pgvector performance | Low | HNSW indexing, query optimization |
|
||||
|
||||
---
|
||||
|
||||
## Post-MVP Roadmap
|
||||
|
||||
### Future Enhancements
|
||||
- [ ] Character templates/marketplace
|
||||
- [ ] Voice input/output (TTS/STT)
|
||||
- [ ] Export conversations (PDF, EPUB)
|
||||
- [ ] Mobile app (React Native)
|
||||
- [ ] Plugin system for custom scrapers
|
||||
- [ ] AI-powered character attribute suggestions
|
||||
- [ ] Collaborative story writing
|
||||
- [ ] Public character sharing
|
||||
664
doc/monorepo-guide.md
Normal file
664
doc/monorepo-guide.md
Normal file
@@ -0,0 +1,664 @@
|
||||
# DreamChat Monorepo Guide
|
||||
|
||||
## Overview
|
||||
|
||||
DreamChat uses a pnpm workspace monorepo structure to share code between frontend and backend, particularly for WebSocket types and API DTOs.
|
||||
|
||||
## Monorepo Structure
|
||||
|
||||
```
|
||||
dreamchat/
|
||||
├── apps/
|
||||
│ ├── backend/ # NestJS application
|
||||
│ └── frontend/ # React + Vite application
|
||||
├── packages/
|
||||
│ ├── shared/ # Shared types & interfaces
|
||||
│ └── config/ # Shared configurations (ESLint, TS)
|
||||
├── prisma/ # Database schema (shared)
|
||||
├── pnpm-workspace.yaml
|
||||
└── package.json # Root package.json
|
||||
```
|
||||
|
||||
## Root Configuration
|
||||
|
||||
### package.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "dreamchat",
|
||||
"version": "1.0.0",
|
||||
"private": true,
|
||||
"packageManager": "pnpm@8.15.0",
|
||||
"scripts": {
|
||||
"build": "pnpm -r build",
|
||||
"dev": "pnpm -r --parallel dev",
|
||||
"test": "pnpm -r test",
|
||||
"lint": "pnpm -r lint",
|
||||
"db:migrate": "pnpm --filter backend db:migrate",
|
||||
"db:generate": "prisma generate",
|
||||
"db:studio": "prisma studio",
|
||||
"clean": "pnpm -r clean && rm -rf node_modules"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^20.0.0",
|
||||
"typescript": "^5.3.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### pnpm-workspace.yaml
|
||||
|
||||
```yaml
|
||||
packages:
|
||||
- 'apps/*'
|
||||
- 'packages/*'
|
||||
```
|
||||
|
||||
### .npmrc
|
||||
|
||||
```
|
||||
shamefully-hoist=true
|
||||
auto-install-peers=true
|
||||
strict-peer-dependencies=false
|
||||
```
|
||||
|
||||
## Package Structure
|
||||
|
||||
### 1. Shared Package (`packages/shared`)
|
||||
|
||||
Contains all shared types, interfaces, and DTOs used by both frontend and backend.
|
||||
|
||||
#### packages/shared/package.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@dreamchat/shared",
|
||||
"version": "1.0.0",
|
||||
"main": "./dist/index.js",
|
||||
"types": "./dist/index.d.ts",
|
||||
"exports": {
|
||||
".": {
|
||||
"import": "./dist/index.js",
|
||||
"require": "./dist/index.js",
|
||||
"types": "./dist/index.d.ts"
|
||||
},
|
||||
"./websocket": {
|
||||
"import": "./dist/websocket/index.js",
|
||||
"types": "./dist/websocket/index.d.ts"
|
||||
},
|
||||
"./api": {
|
||||
"import": "./dist/api/index.js",
|
||||
"types": "./dist/api/index.d.ts"
|
||||
}
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc",
|
||||
"dev": "tsc --watch",
|
||||
"clean": "rm -rf dist"
|
||||
},
|
||||
"devDependencies": {
|
||||
"typescript": "^5.3.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### packages/shared/tsconfig.json
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"declaration": true,
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"forceConsistentCasingInFileNames": true
|
||||
},
|
||||
"include": ["src/**/*"],
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
```
|
||||
|
||||
#### packages/shared/src/websocket/events.ts
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* WebSocket Event Types
|
||||
* Shared between frontend and backend for type-safe communication
|
||||
*/
|
||||
|
||||
export enum WebSocketEventType {
|
||||
// Client -> Server
|
||||
JOIN_CONVERSATION = 'JOIN_CONVERSATION',
|
||||
LEAVE_CONVERSATION = 'LEAVE_CONVERSATION',
|
||||
SEND_MESSAGE = 'SEND_MESSAGE',
|
||||
STOP_GENERATION = 'STOP_GENERATION',
|
||||
|
||||
// Server -> Client
|
||||
CONVERSATION_JOINED = 'CONVERSATION_JOINED',
|
||||
MESSAGE_ACK = 'MESSAGE_ACK',
|
||||
STREAM_CHUNK = 'STREAM_CHUNK',
|
||||
STREAM_COMPLETE = 'STREAM_COMPLETE',
|
||||
ERROR = 'ERROR',
|
||||
}
|
||||
|
||||
// Base message interface
|
||||
export interface WebSocketMessage<T = unknown> {
|
||||
type: WebSocketEventType;
|
||||
payload: T;
|
||||
timestamp: string;
|
||||
requestId?: string;
|
||||
}
|
||||
|
||||
// Client -> Server payloads
|
||||
export interface JoinConversationPayload {
|
||||
conversationId: string;
|
||||
}
|
||||
|
||||
export interface LeaveConversationPayload {
|
||||
conversationId: string;
|
||||
}
|
||||
|
||||
export interface SendMessagePayload {
|
||||
conversationId: string;
|
||||
content: string;
|
||||
streaming?: boolean;
|
||||
}
|
||||
|
||||
export interface StopGenerationPayload {
|
||||
conversationId: string;
|
||||
}
|
||||
|
||||
// Server -> Client payloads
|
||||
export interface ConversationJoinedPayload {
|
||||
conversationId: string;
|
||||
history: MessageHistoryItem[];
|
||||
}
|
||||
|
||||
export interface MessageHistoryItem {
|
||||
id: string;
|
||||
role: 'user' | 'assistant' | 'system';
|
||||
content: string;
|
||||
createdAt: string;
|
||||
}
|
||||
|
||||
export interface MessageAckPayload {
|
||||
messageId: string;
|
||||
status: 'received' | 'processing' | 'error';
|
||||
}
|
||||
|
||||
export interface StreamChunkPayload {
|
||||
conversationId: string;
|
||||
chunk: string;
|
||||
isComplete: boolean;
|
||||
}
|
||||
|
||||
export interface StreamCompletePayload {
|
||||
conversationId: string;
|
||||
messageId: string;
|
||||
content: string;
|
||||
tokensUsed?: number;
|
||||
model?: string;
|
||||
}
|
||||
|
||||
export interface ErrorPayload {
|
||||
code: string;
|
||||
message: string;
|
||||
details?: Record<string, unknown>;
|
||||
}
|
||||
```
|
||||
|
||||
#### packages/shared/src/websocket/index.ts
|
||||
|
||||
```typescript
|
||||
export * from './events.js';
|
||||
```
|
||||
|
||||
#### packages/shared/src/api/dto.ts
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Shared API DTOs
|
||||
* Used by backend for validation and frontend for type safety
|
||||
*/
|
||||
|
||||
// Character DTOs
|
||||
export interface CreateCharacterDto {
|
||||
name: string;
|
||||
personalityPrompt: string;
|
||||
backstory?: string;
|
||||
attributes?: Record<string, unknown>;
|
||||
avatarUrl?: string;
|
||||
config?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
export interface UpdateCharacterDto extends Partial<CreateCharacterDto> {}
|
||||
|
||||
export interface CharacterResponseDto {
|
||||
id: string;
|
||||
name: string;
|
||||
avatarUrl?: string;
|
||||
personalityPrompt: string;
|
||||
backstory?: string;
|
||||
attributes: Record<string, unknown>;
|
||||
config: Record<string, unknown>;
|
||||
isPublic: boolean;
|
||||
createdAt: string;
|
||||
updatedAt: string;
|
||||
}
|
||||
|
||||
// Conversation DTOs
|
||||
export interface CreateConversationDto {
|
||||
characterId: string;
|
||||
title?: string;
|
||||
}
|
||||
|
||||
export interface ConversationResponseDto {
|
||||
id: string;
|
||||
title?: string;
|
||||
characterId: string;
|
||||
messageCount: number;
|
||||
totalTokens: number;
|
||||
createdAt: string;
|
||||
updatedAt: string;
|
||||
}
|
||||
|
||||
// Message DTOs
|
||||
export interface CreateMessageDto {
|
||||
content: string;
|
||||
}
|
||||
|
||||
export interface MessageResponseDto {
|
||||
id: string;
|
||||
role: 'user' | 'assistant' | 'system';
|
||||
content: string;
|
||||
tokensUsed?: number;
|
||||
model?: string;
|
||||
metadata?: Record<string, unknown>;
|
||||
createdAt: string;
|
||||
}
|
||||
|
||||
// Auth DTOs
|
||||
export interface LoginDto {
|
||||
username: string;
|
||||
password: string;
|
||||
}
|
||||
|
||||
export interface RegisterDto {
|
||||
email: string;
|
||||
username: string;
|
||||
password: string;
|
||||
}
|
||||
|
||||
export interface AuthResponseDto {
|
||||
accessToken: string;
|
||||
refreshToken: string;
|
||||
expiresIn: number;
|
||||
user: UserResponseDto;
|
||||
}
|
||||
|
||||
export interface UserResponseDto {
|
||||
id: string;
|
||||
email: string;
|
||||
username: string;
|
||||
role: 'USER' | 'ADMIN';
|
||||
}
|
||||
```
|
||||
|
||||
#### packages/shared/src/api/index.ts
|
||||
|
||||
```typescript
|
||||
export * from './dto.js';
|
||||
```
|
||||
|
||||
#### packages/shared/src/index.ts
|
||||
|
||||
```typescript
|
||||
export * from './websocket/index.js';
|
||||
export * from './api/index.js';
|
||||
```
|
||||
|
||||
### 2. Backend (`apps/backend`)
|
||||
|
||||
#### apps/backend/package.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@dreamchat/backend",
|
||||
"version": "1.0.0",
|
||||
"scripts": {
|
||||
"build": "nest build",
|
||||
"dev": "nest start --watch",
|
||||
"start": "node dist/main",
|
||||
"test": "jest",
|
||||
"test:watch": "jest --watch",
|
||||
"lint": "eslint \"{src,apps,libs,test}/**/*.ts\"",
|
||||
"db:migrate": "prisma migrate deploy",
|
||||
"db:generate": "prisma generate",
|
||||
"clean": "rm -rf dist"
|
||||
},
|
||||
"dependencies": {
|
||||
"@dreamchat/shared": "workspace:*",
|
||||
"@nestjs/common": "^10.0.0",
|
||||
"@nestjs/core": "^10.0.0",
|
||||
"@nestjs/platform-socket.io": "^10.0.0",
|
||||
"@nestjs/websockets": "^10.0.0",
|
||||
"@prisma/client": "^5.10.0",
|
||||
"@xenova/transformers": "^2.15.0",
|
||||
"socket.io": "^4.7.0",
|
||||
"reflect-metadata": "^0.2.0",
|
||||
"rxjs": "^7.8.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@nestjs/cli": "^10.0.0",
|
||||
"@nestjs/testing": "^10.0.0",
|
||||
"@types/node": "^20.0.0",
|
||||
"jest": "^29.0.0",
|
||||
"prisma": "^5.10.0",
|
||||
"typescript": "^5.3.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Using Shared Package in Backend
|
||||
|
||||
```typescript
|
||||
// apps/backend/src/chat/chat.gateway.ts
|
||||
import {
|
||||
WebSocketEventType,
|
||||
WebSocketMessage,
|
||||
JoinConversationPayload,
|
||||
SendMessagePayload,
|
||||
StreamChunkPayload,
|
||||
ConversationJoinedPayload,
|
||||
} from '@dreamchat/shared';
|
||||
|
||||
@WebSocketGateway({ namespace: 'chat' })
|
||||
export class ChatGateway implements OnGatewayConnection {
|
||||
|
||||
@SubscribeMessage(WebSocketEventType.JOIN_CONVERSATION)
|
||||
async handleJoin(
|
||||
@MessageBody() payload: JoinConversationPayload,
|
||||
@ConnectedSocket() client: Socket,
|
||||
) {
|
||||
// Implementation
|
||||
const response: WebSocketMessage<ConversationJoinedPayload> = {
|
||||
type: WebSocketEventType.CONVERSATION_JOINED,
|
||||
payload: { conversationId: payload.conversationId, history: [] },
|
||||
timestamp: new Date().toISOString(),
|
||||
};
|
||||
client.emit(response.type, response);
|
||||
}
|
||||
|
||||
@SubscribeMessage(WebSocketEventType.SEND_MESSAGE)
|
||||
async handleMessage(
|
||||
@MessageBody() payload: SendMessagePayload,
|
||||
@ConnectedSocket() client: Socket,
|
||||
) {
|
||||
// Stream chunks with type safety
|
||||
const chunk: WebSocketMessage<StreamChunkPayload> = {
|
||||
type: WebSocketEventType.STREAM_CHUNK,
|
||||
payload: {
|
||||
conversationId: payload.conversationId,
|
||||
chunk: ' partial text',
|
||||
isComplete: false,
|
||||
},
|
||||
timestamp: new Date().toISOString(),
|
||||
};
|
||||
client.emit(chunk.type, chunk);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Frontend (`apps/frontend`)
|
||||
|
||||
#### apps/frontend/package.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "@dreamchat/frontend",
|
||||
"version": "1.0.0",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "vite",
|
||||
"build": "tsc && vite build",
|
||||
"preview": "vite preview",
|
||||
"test": "vitest",
|
||||
"lint": "eslint . --ext ts,tsx",
|
||||
"clean": "rm -rf dist"
|
||||
},
|
||||
"dependencies": {
|
||||
"@dreamchat/shared": "workspace:*",
|
||||
"@tanstack/react-query": "^5.0.0",
|
||||
"react": "^18.2.0",
|
||||
"react-dom": "^18.2.0",
|
||||
"react-router-dom": "^6.20.0",
|
||||
"socket.io-client": "^4.7.0",
|
||||
"zustand": "^4.5.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/react": "^18.2.0",
|
||||
"@types/react-dom": "^18.2.0",
|
||||
"@vitejs/plugin-react": "^4.2.0",
|
||||
"typescript": "^5.3.0",
|
||||
"vite": "^5.0.0",
|
||||
"vitest": "^1.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Using Shared Package in Frontend
|
||||
|
||||
```typescript
|
||||
// apps/frontend/src/hooks/use-chat.ts
|
||||
import { useCallback } from 'react';
|
||||
import { io, Socket } from 'socket.io-client';
|
||||
import {
|
||||
WebSocketEventType,
|
||||
WebSocketMessage,
|
||||
JoinConversationPayload,
|
||||
SendMessagePayload,
|
||||
StreamChunkPayload,
|
||||
StreamCompletePayload,
|
||||
} from '@dreamchat/shared';
|
||||
|
||||
export function useChat(conversationId: string) {
|
||||
const [socket, setSocket] = useState<Socket | null>(null);
|
||||
const [messages, setMessages] = useState<string[]>([]);
|
||||
|
||||
useEffect(() => {
|
||||
const s = io('ws://localhost:3000/chat', {
|
||||
auth: { token: getAuthToken() },
|
||||
});
|
||||
|
||||
s.on(WebSocketEventType.STREAM_CHUNK, (msg: WebSocketMessage<StreamChunkPayload>) => {
|
||||
setMessages((prev) => [...prev, msg.payload.chunk]);
|
||||
});
|
||||
|
||||
s.on(WebSocketEventType.STREAM_COMPLETE, (msg: WebSocketMessage<StreamCompletePayload>) => {
|
||||
// Handle completion
|
||||
});
|
||||
|
||||
setSocket(s);
|
||||
|
||||
// Join conversation
|
||||
const joinPayload: JoinConversationPayload = { conversationId };
|
||||
s.emit(WebSocketEventType.JOIN_CONVERSATION, joinPayload);
|
||||
|
||||
return () => {
|
||||
s.disconnect();
|
||||
};
|
||||
}, [conversationId]);
|
||||
|
||||
const sendMessage = useCallback((content: string) => {
|
||||
if (!socket) return;
|
||||
|
||||
const payload: SendMessagePayload = {
|
||||
conversationId,
|
||||
content,
|
||||
streaming: true,
|
||||
};
|
||||
socket.emit(WebSocketEventType.SEND_MESSAGE, payload);
|
||||
}, [socket, conversationId]);
|
||||
|
||||
return { messages, sendMessage };
|
||||
}
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Initial Setup
|
||||
|
||||
```bash
|
||||
# 1. Install pnpm (if not already installed)
|
||||
npm install -g pnpm
|
||||
|
||||
# 2. Clone and setup
|
||||
git clone <repo-url>
|
||||
cd dreamchat
|
||||
|
||||
# 3. Install all dependencies
|
||||
pnpm install
|
||||
|
||||
# 4. Build shared packages first
|
||||
pnpm --filter @dreamchat/shared build
|
||||
|
||||
# 5. Generate Prisma client
|
||||
pnpm db:generate
|
||||
|
||||
# 6. Start development (runs all apps in parallel)
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
### Adding Dependencies
|
||||
|
||||
```bash
|
||||
# Add dependency to root
|
||||
pnpm add -D typescript
|
||||
|
||||
# Add dependency to specific app
|
||||
pnpm --filter @dreamchat/backend add @nestjs/jwt
|
||||
|
||||
# Add dependency to shared package
|
||||
pnpm --filter @dreamchat/shared add zod
|
||||
|
||||
# Add shared package to backend/frontend
|
||||
pnpm --filter @dreamchat/backend add @dreamchat/shared@workspace:*
|
||||
```
|
||||
|
||||
### Building
|
||||
|
||||
```bash
|
||||
# Build all packages
|
||||
pnpm build
|
||||
|
||||
# Build specific package
|
||||
pnpm --filter @dreamchat/shared build
|
||||
|
||||
# Watch mode for shared package (during development)
|
||||
pnpm --filter @dreamchat/shared dev
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Test all
|
||||
pnpm test
|
||||
|
||||
# Test specific package
|
||||
pnpm --filter @dreamchat/backend test
|
||||
|
||||
# Test with coverage
|
||||
pnpm --filter @dreamchat/backend test --coverage
|
||||
```
|
||||
|
||||
## Docker Integration
|
||||
|
||||
### Development Docker Compose
|
||||
|
||||
```yaml
|
||||
# docker-compose.dev.yml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
backend:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: apps/backend/Dockerfile
|
||||
target: development
|
||||
volumes:
|
||||
- .:/workspace
|
||||
- /workspace/node_modules
|
||||
- /workspace/apps/backend/node_modules
|
||||
- /workspace/packages/shared/node_modules
|
||||
environment:
|
||||
- NODE_ENV=development
|
||||
command: pnpm --filter @dreamchat/backend dev
|
||||
|
||||
frontend:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: apps/frontend/Dockerfile
|
||||
target: development
|
||||
volumes:
|
||||
- .:/workspace
|
||||
- /workspace/node_modules
|
||||
- /workspace/apps/frontend/node_modules
|
||||
- /workspace/packages/shared/node_modules
|
||||
command: pnpm --filter @dreamchat/frontend dev
|
||||
```
|
||||
|
||||
### Production Dockerfile (Backend)
|
||||
|
||||
```dockerfile
|
||||
# apps/backend/Dockerfile
|
||||
FROM node:20-alpine AS base
|
||||
RUN npm install -g pnpm
|
||||
|
||||
FROM base AS dependencies
|
||||
WORKDIR /app
|
||||
COPY pnpm-workspace.yaml package.json ./
|
||||
COPY apps/backend/package.json ./apps/backend/
|
||||
COPY packages/shared/package.json ./packages/shared/
|
||||
RUN pnpm install --frozen-lockfile
|
||||
|
||||
FROM base AS build
|
||||
WORKDIR /app
|
||||
COPY --from=dependencies /app/node_modules ./node_modules
|
||||
COPY --from=dependencies /app/apps/backend/node_modules ./apps/backend/node_modules
|
||||
COPY --from=dependencies /app/packages/shared/node_modules ./packages/shared/node_modules
|
||||
COPY . .
|
||||
RUN pnpm --filter @dreamchat/shared build
|
||||
RUN pnpm --filter @dreamchat/backend build
|
||||
|
||||
FROM base AS production
|
||||
WORKDIR /app
|
||||
COPY --from=build /app/apps/backend/dist ./dist
|
||||
COPY --from=build /app/apps/backend/node_modules ./node_modules
|
||||
COPY --from=build /app/node_modules ./node_modules
|
||||
EXPOSE 3000
|
||||
CMD ["node", "dist/main.js"]
|
||||
```
|
||||
|
||||
## Benefits of This Structure
|
||||
|
||||
1. **Type Safety**: Shared WebSocket events and DTOs ensure frontend and backend stay in sync
|
||||
2. **Single Source of Truth**: Changes to types in `packages/shared` propagate to both apps
|
||||
3. **Efficient Development**: pnpm workspaces deduplicate dependencies, saving disk space
|
||||
4. **Simplified CI/CD**: Single repository with unified versioning
|
||||
5. **Code Reuse**: Utilities and constants can be shared
|
||||
|
||||
## Migration from Non-Monorepo
|
||||
|
||||
If migrating an existing project:
|
||||
|
||||
1. Create new monorepo structure
|
||||
2. Move backend to `apps/backend`
|
||||
3. Move frontend to `apps/frontend`
|
||||
4. Extract shared types to `packages/shared`
|
||||
5. Update all imports to use `@dreamchat/shared`
|
||||
6. Update Docker files to use pnpm
|
||||
Reference in New Issue
Block a user